@gustavobrunodev/ai-tools 1.0.1 → 1.1.0

package/src/hooks/useFilter.ts

@@ -0,0 +1,31 @@
+import { useMemo, useState } from 'react'
+
+interface FilterOptions<T> {
+  keys: (keyof T & string)[]
+}
+
+export function useFilter<T>(items: T[], options: FilterOptions<T>) {
+  const [query, setQuery] = useState('')
+
+  const filtered = useMemo(() => {
+    if (!query.trim()) return items
+
+    const tokens = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 0)
+
+    return items.filter((item) => {
+      const searchable = options.keys
+        .map((key) => {
+          const value = item[key]
+          return typeof value === 'string' ? value.toLowerCase() : ''
+        })
+        .join(' ')
+
+      return tokens.every((token) => searchable.includes(token))
+    })
+  }, [query, items, options.keys])
+
+  return { query, setQuery, filtered, hasFilter: query.trim().length > 0 }
+}

package/src/hooks/useInstaller.ts

@@ -0,0 +1,39 @@
+import { useState } from 'react'
+
+import { installSkills } from '../services/installer'
+import { getSkillWithPath } from '../services/skills-provider'
+import type { InstallOptions, InstallResult, SkillInfo } from '../types'
+
+export function useInstaller() {
+  const [progress, setProgress] = useState({ current: 0, total: 0, skill: '' })
+  const [results, setResults] = useState<InstallResult[]>([])
+  const [installing, setInstalling] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const install = async (skills: SkillInfo[], options: InstallOptions) => {
+    setInstalling(true)
+    setError(null)
+    setProgress({ current: 0, total: skills.length * options.agents.length, skill: 'Downloading...' })
+
+    const resolvedSkills: SkillInfo[] = []
+    for (const skill of skills) {
+      const resolved = skill.path ? skill : await getSkillWithPath(skill.name)
+      if (resolved) resolvedSkills.push(resolved)
+    }
+
+    setProgress({ current: 0, total: resolvedSkills.length * options.agents.length, skill: 'Installing...' })
+
+    try {
+      const res = await installSkills(resolvedSkills, options)
+      setResults(res)
+      return res
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : String(err))
+      return []
+    } finally {
+      setInstalling(false)
+    }
+  }
+
+  return { install, progress, results, installing, error }
+}

package/src/hooks/useKeyboardNav.ts

@@ -0,0 +1,39 @@
+import { useInput } from 'ink'
+import { useState } from 'react'
+
+export interface KeyNavOptions {
+  cols?: number
+  isGrid?: boolean
+  loop?: boolean
+}
+
+export function useKeyboardNav(itemCount: number, options: KeyNavOptions = {}) {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const { cols = 1, isGrid = false, loop = true } = options
+
+  useInput((_input, key) => {
+    const keyHandlers: Record<string, () => void> = {
+      upArrow: () =>
+        setSelectedIndex((prev) => {
+          if (prev - cols < 0) return loop ? itemCount - 1 : prev
+          return prev - cols
+        }),
+      downArrow: () =>
+        setSelectedIndex((prev) => {
+          if (prev + cols >= itemCount) return loop ? 0 : prev
+          return prev + cols
+        }),
+      leftArrow: () => isGrid && setSelectedIndex((prev) => (prev > 0 ? prev - 1 : loop ? itemCount - 1 : prev)),
+      rightArrow: () => isGrid && setSelectedIndex((prev) => (prev < itemCount - 1 ? prev + 1 : loop ? 0 : prev)),
+      pageUp: () => setSelectedIndex((prev) => Math.max(0, prev - 10)),
+      pageDown: () => setSelectedIndex((prev) => Math.min(itemCount - 1, prev + 10)),
+      home: () => setSelectedIndex(0),
+      end: () => setSelectedIndex(itemCount - 1),
+    }
+
+    const pressedKey = Object.keys(key).find((k) => key[k as keyof typeof key])
+    if (pressedKey && keyHandlers[pressedKey]) keyHandlers[pressedKey]()
+  })
+
+  return { selectedIndex, setSelectedIndex }
+}

package/src/hooks/useKonamiCode.ts

@@ -0,0 +1,48 @@
+import { useInput } from 'ink'
+import { useCallback, useRef, useState } from 'react'
+
+const KONAMI_SEQUENCE = ['up', 'up', 'down', 'down', 'left', 'right', 'left', 'right', 'b', 'a'] as const
+
+type KonamiKey = (typeof KONAMI_SEQUENCE)[number]
+
+export function useKonamiCode() {
+  const [activated, setActivated] = useState(false)
+  const bufferRef = useRef<KonamiKey[]>([])
+
+  useInput((input, key) => {
+    if (activated) return
+    let mapped: KonamiKey | null = null
+    if (key.upArrow) mapped = 'up'
+    else if (key.downArrow) mapped = 'down'
+    else if (key.leftArrow) mapped = 'left'
+    else if (key.rightArrow) mapped = 'right'
+    else if (input.toLowerCase() === 'b') mapped = 'b'
+    else if (input.toLowerCase() === 'a') mapped = 'a'
+
+    if (!mapped) {
+      bufferRef.current = []
+      return
+    }
+
+    bufferRef.current.push(mapped)
+
+    if (bufferRef.current.length > KONAMI_SEQUENCE.length) {
+      bufferRef.current = bufferRef.current.slice(-KONAMI_SEQUENCE.length)
+    }
+
+    if (
+      bufferRef.current.length === KONAMI_SEQUENCE.length &&
+      bufferRef.current.every((k, i) => k === KONAMI_SEQUENCE[i])
+    ) {
+      setActivated(true)
+      bufferRef.current = []
+    }
+  })
+
+  const reset = useCallback(() => {
+    setActivated(false)
+    bufferRef.current = []
+  }, [])
+
+  return { activated, reset }
+}

package/src/hooks/useRemover.ts

@@ -0,0 +1,59 @@
+import { useState } from 'react'
+
+import { removeSkill } from '../services/installer'
+import type { AgentType } from '../types'
+
+export interface RemoveResult {
+  skill: string
+  agent: string
+  success: boolean
+  error?: string
+}
+
+export function useRemover() {
+  const [progress, setProgress] = useState({ current: 0, total: 0, skill: '' })
+  const [results, setResults] = useState<RemoveResult[]>([])
+  const [removing, setRemoving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const remove = async (skillName: string, agents: AgentType[], global = false) => {
+    setRemoving(true)
+    setProgress({ current: 0, total: agents.length, skill: skillName })
+    setError(null)
+
+    try {
+      const res = await removeSkill(skillName, agents, { global })
+      setResults((prev) => [...prev, ...res])
+      return res
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : String(err))
+      return []
+    } finally {
+      setRemoving(false)
+    }
+  }
+
+  const removeMultiple = async (skillsToRemove: { name: string; agents: AgentType[] }[]) => {
+    setRemoving(true)
+    const totalOps = skillsToRemove.reduce((acc, item) => acc + item.agents.length, 0)
+    setProgress({ current: 0, total: totalOps, skill: 'Initializing...' })
+    setResults([])
+    setError(null)
+
+    try {
+      let completedOps = 0
+      for (const item of skillsToRemove) {
+        setProgress({ current: completedOps, total: totalOps, skill: item.name })
+        const res = await removeSkill(item.name, item.agents, {})
+        setResults((prev) => [...prev, ...res])
+        completedOps += item.agents.length
+      }
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setRemoving(false)
+    }
+  }
+
+  return { remove, removeMultiple, progress, results, removing, error }
+}

package/src/hooks/useSkillContent.ts

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { useEffect, useState } from 'react'
+
+import { ensureSkillDownloaded, getSkillCachePath, getSkillMetadata, type SkillMetadata } from '../services/registry'
+
+export interface SkillContent {
+  metadata: SkillMetadata | null
+  content: string | null
+  loading: boolean
+  error: string | null
+}
+
+export function useSkillContent(skillName: string | null): SkillContent {
+  const [metadata, setMetadata] = useState<SkillMetadata | null>(null)
+  const [content, setContent] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!skillName) {
+      setMetadata(null)
+      setContent(null)
+      setLoading(false)
+      setError(null)
+      return
+    }
+
+    let mounted = true
+    setLoading(true)
+    setError(null)
+
+    const load = async () => {
+      try {
+        const [meta, cachePath] = await Promise.all([
+          getSkillMetadata(skillName).catch(() => null),
+          ensureSkillDownloaded(skillName).catch(() => null),
+        ])
+
+        if (!mounted) return
+        if (meta) setMetadata(meta)
+
+        const resolvedPath = cachePath ?? getSkillCachePath(skillName)
+
+        try {
+          const skillMd = readFileSync(join(resolvedPath, 'SKILL.md'), 'utf-8')
+          setContent(skillMd)
+        } catch {
+          setError('Failed to load skill content')
+        }
+      } catch (err: unknown) {
+        if (mounted) {
+          setError(err instanceof Error ? err.message : String(err))
+        }
+      } finally {
+        if (mounted) setLoading(false)
+      }
+    }
+
+    load()
+    return () => {
+      mounted = false
+    }
+  }, [skillName])
+
+  return { metadata, content, loading, error }
+}

package/src/hooks/useSkills.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react'
+
+import { groupSkillsByCategory } from '../services/categories'
+import { discoverSkillsAsync } from '../services/skills-provider'
+import type { GroupedSkills, SkillInfo } from '../types'
+
+export function useSkills() {
+  const [skills, setSkills] = useState<SkillInfo[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [groupedSkills, setGroupedSkills] = useState<GroupedSkills>(new Map())
+
+  useEffect(() => {
+    let mounted = true
+
+    const load = async () => {
+      try {
+        const data = await discoverSkillsAsync()
+
+        if (mounted) {
+          setSkills(data)
+          setGroupedSkills(groupSkillsByCategory(data))
+        }
+      } catch (err: unknown) {
+        if (mounted) setError(err instanceof Error ? err.message : String(err))
+      } finally {
+        if (mounted) setLoading(false)
+      }
+    }
+
+    load()
+    return () => {
+      mounted = false
+    }
+  }, [])
+
+  return { skills, loading, error, groupedSkills }
+}

package/src/hooks/useWizardStep.ts

@@ -0,0 +1,19 @@
+import { useState } from 'react'
+
+export function useWizardStep(totalSteps: number) {
+  const [step, setStep] = useState(1)
+
+  const next = () => setStep((s) => Math.min(s + 1, totalSteps))
+  const back = () => setStep((s) => Math.max(s - 1, 1))
+  const goTo = (s: number) => setStep(s)
+
+  return {
+    step,
+    next,
+    back,
+    goTo,
+    isFirst: step === 1,
+    isLast: step === totalSteps,
+    progress: step / totalSteps,
+  }
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+import { Command } from 'commander'
+import { render } from 'ink'
+import React from 'react'
+
+import { App } from './app'
+import { PACKAGE_VERSION } from './services/package-info'
+
+const program = new Command()
+
+// Root command — default action (no subcommand) → interactive install
+program
+  .name('ai-tools')
+  .description('CLI to install and manage AI tools (Skills, MCPs, Agents) for AI coding agents')
+  .version(PACKAGE_VERSION)
+  .action(() => {
+    render(React.createElement(App, { command: 'install' }))
+  })
+
+// Install command
+program
+  .command('install')
+  .description('Install skills (interactive by default)')
+  .option('-g, --global', 'Install globally to user home', false)
+  .option('-s, --skill <names...>', 'Install one or more skills')
+  .option('-a, --agent <agents...>', 'Target specific agents')
+  .option('--symlink', 'Use symlink instead of copy', false)
+  .option('-f, --force', 'Force re-download skills (bypass cache)', false)
+  .action(async (options) => {
+    if (shouldUseInteractiveMode(options)) {
+      render(React.createElement(App, { command: 'install' }))
+      return
+    }
+
+    // CLI mode - dynamic import
+    const { runCliInstall } = await import('./cli/install')
+    await runCliInstall(options)
+  })
+
+// List command
+program
+  .command('list')
+  .alias('ls')
+  .description('List available/installed agent skills')
+  .option('-s, --simple', 'List skills in non-interactive mode (plain output)', false)
+  .action(async (options) => {
+    if (!options.simple) {
+      render(React.createElement(App, { command: 'list' }))
+      return
+    }
+
+    // CLI mode - dynamic import
+    const { runCliList } = await import('./cli/list')
+    await runCliList()
+  })
+
+// Remove command
+program
+  .command('remove')
+  .alias('rm')
+  .description('Remove installed skills')
+  .option('-g, --global', 'Remove from global installation', false)
+  .option('-s, --skill <names...>', 'Remove one or more skills')
+  .option('-a, --agent <agents...>', 'Target specific agents')
+  .option('-f, --force', 'Force removal even if not in lockfile', false)
+  .action(async (options) => {
+    if (shouldUseInteractiveMode(options)) {
+      render(React.createElement(App, { command: 'remove' }))
+      return
+    }
+
+    // CLI mode - dynamic import
+    const { runCliRemove } = await import('./cli/remove')
+    await runCliRemove(options)
+  })
+
+// Update command
+program
+  .command('update')
+  .description('Update installed skills to the latest version')
+  .option('-s, --skill <name>', 'Update a specific skill')
+  .action(async (options) => {
+    if (shouldUseInteractiveMode(options)) {
+      render(React.createElement(App, { command: 'update' }))
+      return
+    }
+
+    // CLI mode - dynamic import
+    const { runCliUpdate } = await import('./cli/update')
+    await runCliUpdate(options)
+  })
+
+// Cache command
+program
+  .command('cache')
+  .description('Manage the skills cache')
+  .option('--clear', 'Clear all cached skills and registry')
+  .option('--clear-registry', 'Clear only the registry cache')
+  .option('--path', 'Show cache directory path')
+  .action(async (options) => {
+    // CLI mode - dynamic import
+    const { runCliCache } = await import('./cli/cache')
+    runCliCache(options)
+  })
+
+// Credits command
+program
+  .command('credits')
+  .description('Show project contributors and credits')
+  .action(() => {
+    render(React.createElement(App, { command: 'credits' }))
+  })
+
+// Audit log command
+program
+  .command('audit')
+  .description('View audit log of skill operations')
+  .option('-n, --limit <number>', 'Number of entries to show', '10')
+  .option('--path', 'Show audit log file path')
+  .action(async (options) => {
+    const { runCliAudit } = await import('./cli/audit')
+    await runCliAudit(options)
+  })
+
+program.parse(process.argv)
+
+function shouldUseInteractiveMode(options: Record<string, unknown>): boolean {
+  const optionKeys = Object.keys(options).filter((key) => key !== 'parent')
+  return optionKeys.length === 0
+}

package/src/services/__tests__/audit-log.spec.ts

@@ -0,0 +1,220 @@
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { AUDIT_LOG_FILE, GLOBAL_CONFIG_DIR } from '../../utils/constants'
+import { getAuditLogPath, logAudit, readAuditLog } from '../audit-log'
+
+describe('Audit Log', () => {
+  const testHome = join(tmpdir(), `.test-ai-tools-${Date.now()}`)
+  const testConfigDir = join(testHome, GLOBAL_CONFIG_DIR)
+  const testLogPath = join(testConfigDir, AUDIT_LOG_FILE)
+
+  beforeAll(async () => {
+    await mkdir(testConfigDir, { recursive: true })
+  })
+
+  afterAll(async () => {
+    await rm(testHome, { recursive: true, force: true })
+  })
+
+  beforeEach(async () => {
+    await rm(testLogPath, { force: true })
+  })
+
+  describe('getAuditLogPath', () => {
+    it('should return path in home directory', () => {
+      const path = getAuditLogPath(testHome)
+      expect(path).toContain(testHome)
+      expect(path).toContain(GLOBAL_CONFIG_DIR)
+      expect(path).toContain(AUDIT_LOG_FILE)
+    })
+  })
+
+  describe('logAudit', () => {
+    it('should create audit log file and write entry', async () => {
+      await logAudit(
+        {
+          action: 'install',
+          skillName: 'test-skill',
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+        },
+        testHome,
+      )
+
+      const entries = await readAuditLog(undefined, testHome)
+      expect(entries).toHaveLength(1)
+      expect(entries[0].skillName).toBe('test-skill')
+      expect(entries[0].action).toBe('install')
+    })
+
+    it('should append to existing audit log', async () => {
+      await logAudit(
+        {
+          action: 'install',
+          skillName: 'skill-1',
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+        },
+        testHome,
+      )
+
+      await logAudit(
+        {
+          action: 'remove',
+          skillName: 'skill-2',
+          agents: ['Claude Code'],
+          success: 1,
+          failed: 0,
+        },
+        testHome,
+      )
+
+      const entries = await readAuditLog(undefined, testHome)
+      expect(entries).toHaveLength(2)
+      expect(entries[0].skillName).toBe('skill-2') // Most recent first
+      expect(entries[1].skillName).toBe('skill-1')
+    })
+
+    it('should include timestamp in log entries', async () => {
+      const beforeTime = Date.now()
+
+      await logAudit(
+        {
+          action: 'install',
+          skillName: 'test-skill',
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+        },
+        testHome,
+      )
+
+      const entries = await readAuditLog(undefined, testHome)
+      // Timestamp string exists now
+      const timestamp = entries[0].timestamp
+      expect(timestamp).toBeDefined()
+      const entryTime = new Date(timestamp!).getTime()
+
+      expect(entryTime).toBeGreaterThanOrEqual(beforeTime)
+      expect(entryTime).toBeLessThanOrEqual(Date.now())
+    })
+  })
+
+  describe('readAuditLog', () => {
+    it('should return empty array if log file does not exist', async () => {
+      const entries = await readAuditLog(undefined, testHome)
+      expect(entries).toEqual([])
+    })
+
+    it('should parse valid log entries', async () => {
+      await mkdir(testConfigDir, { recursive: true })
+      const logContent = [
+        JSON.stringify({
+          action: 'install',
+          skillName: 'skill-1',
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+          timestamp: '2026-02-18T10:00:00.000Z',
+        }),
+        JSON.stringify({
+          action: 'remove',
+          skillName: 'skill-2',
+          agents: ['Claude Code'],
+          success: 1,
+          failed: 0,
+          timestamp: '2026-02-18T11:00:00.000Z',
+        }),
+      ].join('\n')
+
+      await writeFile(testLogPath, logContent, 'utf-8')
+
+      const entries = await readAuditLog(undefined, testHome)
+      expect(entries).toHaveLength(2)
+      expect(entries[0].skillName).toBe('skill-2') // Most recent first
+      expect(entries[1].skillName).toBe('skill-1')
+    })
+
+    it('should skip invalid JSON lines', async () => {
+      await mkdir(testConfigDir, { recursive: true })
+      const logContent = [
+        JSON.stringify({
+          action: 'install',
+          skillName: 'skill-1',
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+          timestamp: '2026-02-18T10:00:00.000Z',
+        }),
+        'invalid json line',
+        JSON.stringify({
+          action: 'remove',
+          skillName: 'skill-2',
+          agents: ['Claude Code'],
+          success: 1,
+          failed: 0,
+          timestamp: '2026-02-18T11:00:00.000Z',
+        }),
+      ].join('\n')
+
+      await writeFile(testLogPath, logContent, 'utf-8')
+
+      const entries = await readAuditLog(undefined, testHome)
+      expect(entries).toHaveLength(2)
+      expect(entries[0].skillName).toBe('skill-2')
+      expect(entries[1].skillName).toBe('skill-1')
+    })
+
+    it('should respect limit parameter', async () => {
+      await mkdir(testConfigDir, { recursive: true })
+      const logContent = Array.from({ length: 20 }, (_, i) =>
+        JSON.stringify({
+          action: 'install',
+          skillName: `skill-${i}`,
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+          timestamp: new Date(Date.now() + i * 1000).toISOString(),
+        }),
+      ).join('\n')
+
+      await writeFile(testLogPath, logContent, 'utf-8')
+
+      const entries = await readAuditLog(5, testHome)
+      expect(entries).toHaveLength(5)
+      expect(entries[0].skillName).toBe('skill-19') // Most recent
+    })
+
+    it('should handle empty lines', async () => {
+      await mkdir(testConfigDir, { recursive: true })
+      const logContent = [
+        JSON.stringify({
+          action: 'install',
+          skillName: 'skill-1',
+          agents: ['Cursor'],
+          success: 1,
+          failed: 0,
+          timestamp: '2026-02-18T10:00:00.000Z',
+        }),
+        '',
+        '',
+        JSON.stringify({
+          action: 'remove',
+          skillName: 'skill-2',
+          agents: ['Claude Code'],
+          success: 1,
+          failed: 0,
+          timestamp: '2026-02-18T11:00:00.000Z',
+        }),
+      ].join('\n')
+
+      await writeFile(testLogPath, logContent, 'utf-8')
+      const entries = await readAuditLog(undefined, testHome)
+      expect(entries).toHaveLength(2)
+    })
+  })
+})