@skillsgate/tui 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillsgate/tui",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "bin": {
     "skillsgate-tui": "bin/skillsgate-tui"

package/src/data/use-installed-skills.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react"
+import { useEffect, useRef } from "react"
 import fs from "node:fs/promises"
 import path from "node:path"
 import os from "node:os"
@@ -8,6 +8,7 @@ import { useDb } from "../db/context.js"
 import { agents } from "../../../cli/src/core/agents.js"
 import { readSkillLock } from "../../../cli/src/core/skill-lock.js"
 import { SKILL_MD } from "../../../cli/src/constants.js"
+import { loadCachedSkills, saveCachedSkills, type CachedSkill } from "../db/skills-cache.js"
 import type { EnrichedSkill } from "../store/types.js"
 import type { AgentType, SkillLockFile } from "../../../cli/src/types.js"
 
@@ -92,111 +93,121 @@ async function listSupportingFiles(skillDir: string): Promise<Array<{ relativePa
   return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))
 }
 
+/**
+ * Convert cached skill rows into lightweight EnrichedSkill objects
+ * suitable for rendering the list immediately on startup.
+ */
+function cachedToEnriched(cached: CachedSkill[], lock: SkillLockFile): EnrichedSkill[] {
+  return cached.map((c) => ({
+    name: c.name,
+    description: c.description,
+    filePath: path.join(c.canonicalPath, SKILL_MD),
+    canonicalPath: c.canonicalPath,
+    agents: c.agents,
+    scope: c.scope,
+    projectName: c.scope === "project" ? getProjectNameForPath(c.canonicalPath) : null,
+    hasSupportingFiles: false,
+    supportingFiles: [],
+    metadata: {} as Record<string, unknown>,
+    lock: lock.skills[c.folderName],
+  }))
+}
+
+/**
+ * Convert EnrichedSkill objects from a full scan into CachedSkill rows
+ * for persistence in the SQLite database.
+ */
+function enrichedToCached(skills: EnrichedSkill[]): CachedSkill[] {
+  const now = new Date().toISOString()
+  return skills.map((s) => ({
+    canonicalPath: s.canonicalPath,
+    folderName: path.basename(s.canonicalPath),
+    name: s.name,
+    description: s.description,
+    agents: s.agents,
+    agentShortCodes: [],
+    scope: s.scope,
+    source: s.lock?.source ?? null,
+    sourceType: s.lock?.sourceType ?? null,
+    fileModTime: now,
+    scannedAt: now,
+  }))
+}
+
+/**
+ * Dispatch agent counts derived from the given skills array.
+ */
+function dispatchAgentCounts(
+  skills: EnrichedSkill[],
+  dispatch: ReturnType<typeof useDispatch>,
+): void {
+  const agentCounts = new Map<AgentType, number>()
+  for (const skill of skills) {
+    for (const agentName of skill.agents) {
+      agentCounts.set(agentName, (agentCounts.get(agentName) ?? 0) + 1)
+    }
+  }
+  dispatch({ type: "UPDATE_AGENT_COUNTS", counts: Object.fromEntries(agentCounts) })
+}
+
 /**
  * Scans all detected agent globalSkillsDir paths for SKILL.md files,
  * parses them with gray-matter, enriches with lock file data, and
  * populates the store.
+ *
+ * On first mount, cached results are served instantly while a background
+ * rescan runs. Subsequent tab switches reuse the cache. Press `r` to
+ * force a full rescan.
  */
 export function useInstalledSkills() {
   const dispatch = useDispatch()
   const { installedLoading } = useStore()
-  const { settings } = useDb()
+  const { db, settings } = useDb()
+  const hasLoadedCache = useRef(false)
 
   useEffect(() => {
-    // Only scan when installedLoading is true (initial mount or refresh triggered)
+    // Only act when installedLoading is true (initial mount or refresh triggered)
     if (!installedLoading) return
 
     let cancelled = false
 
-    async function scan() {
-      dispatch({ type: "SET_INSTALLED_LOADING", loading: true })
-
-      try {
-        const lock = await readSkillLock()
-        // Map: skillName -> EnrichedSkill (deduplicating across agents)
-        const skillMap = new Map<string, EnrichedSkill>()
-
-        // Scan each agent's global skills directory
-        for (const agent of Object.values(agents)) {
-          const skillsDir = agent.globalSkillsDir
-          try {
-            const entries = await fs.readdir(skillsDir, { withFileTypes: true })
-            for (const entry of entries) {
-              // Include both real directories and symlinks (skills are often symlinked)
-              if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
-
-              const skillDirPath = path.join(skillsDir, entry.name)
-              const canonicalPath = await fs.realpath(skillDirPath).catch(() => skillDirPath)
-              const skillMdPath = path.join(skillDirPath, SKILL_MD)
-              try {
-                const raw = await fs.readFile(skillMdPath, "utf-8")
-                const { data: frontmatter } = matter(raw)
-                const skillName = entry.name
-                const canonicalPath = await fs.realpath(skillDirPath).catch(() => skillDirPath)
-                const scope = getScopeForPath(canonicalPath)
-                const supportingFiles = await listSupportingFiles(canonicalPath)
-
-                const existing = skillMap.get(canonicalPath)
-                if (existing) {
-                  // Skill already seen from another agent - add this agent
-                  if (!existing.agents.includes(agent.name)) {
-                    existing.agents.push(agent.name)
-                  }
-                } else {
-                  skillMap.set(canonicalPath, {
-                    name: skillName,
-                    description:
-                      (frontmatter.description as string) ??
-                      extractFirstLine(raw),
-                    filePath: skillMdPath,
-                    canonicalPath,
-                    agents: [agent.name],
-                    scope,
-                    projectName:
-                      scope === "project" ? getProjectNameForPath(canonicalPath) : null,
-                    hasSupportingFiles: supportingFiles.length > 0,
-                    supportingFiles,
-                    metadata: frontmatter as Record<string, unknown>,
-                    lock: lock.skills[skillName],
-                  })
-                }
-              } catch {
-                // SKILL.md not found or unreadable in this directory - skip
-              }
-            }
-          } catch {
-            // Agent skills directory doesn't exist - skip
-          }
-        }
-
-        const customScanPaths = settings.get<string[]>("scan.customPaths", [])
-        for (const customPath of customScanPaths) {
-          const resolvedRoot = path.resolve(customPath.replace(/^~(?=$|\/|\\)/, home))
-          const collected = await collectCustomSkills(resolvedRoot, lock)
-          for (const skill of collected) {
-            if (!skillMap.has(skill.canonicalPath)) {
-              skillMap.set(skill.canonicalPath, skill)
+    async function loadFromCacheAndScan() {
+      const isInitialLoad = !hasLoadedCache.current
+
+      // On initial load, try serving from cache first for instant startup
+      if (isInitialLoad) {
+        try {
+          const cached = loadCachedSkills(db)
+          if (cached.length > 0) {
+            const lock = await readSkillLock()
+            const skills = cachedToEnriched(cached, lock)
+            if (!cancelled) {
+              dispatch({ type: "SET_INSTALLED_SKILLS", skills })
+              dispatchAgentCounts(skills, dispatch)
+              hasLoadedCache.current = true
             }
           }
+        } catch {
+          // Cache read failed; fall through to full scan
         }
+      }
 
+      // Run full filesystem scan (in background after cache, or blocking on refresh)
+      try {
+        const scannedSkills = await fullScan(settings)
         if (cancelled) return
 
-        const skills = Array.from(skillMap.values()).sort((a, b) =>
-          a.name.localeCompare(b.name)
-        )
-
-        dispatch({ type: "SET_INSTALLED_SKILLS", skills })
-
-        // Update agent skill counts (without removing agents that have 0 skills)
-        const agentCounts = new Map<AgentType, number>()
-        for (const skill of skills) {
-          for (const agentName of skill.agents) {
-            agentCounts.set(agentName, (agentCounts.get(agentName) ?? 0) + 1)
-          }
+        // Persist to cache
+        try {
+          saveCachedSkills(db, enrichedToCached(scannedSkills))
+        } catch {
+          // Cache write failed; non-critical
         }
 
-        dispatch({ type: "UPDATE_AGENT_COUNTS", counts: Object.fromEntries(agentCounts) })
+        hasLoadedCache.current = true
+
+        dispatch({ type: "SET_INSTALLED_SKILLS", skills: scannedSkills })
+        dispatchAgentCounts(scannedSkills, dispatch)
       } catch {
         if (!cancelled) {
           dispatch({ type: "SET_INSTALLED_SKILLS", skills: [] })
@@ -204,11 +215,88 @@ export function useInstalledSkills() {
       }
     }
 
-    scan()
+    loadFromCacheAndScan()
     return () => { cancelled = true }
   }, [installedLoading])
 }
 
+/**
+ * Performs a full filesystem scan across all agent directories and custom paths.
+ */
+async function fullScan(
+  settings: ReturnType<typeof useDb>["settings"],
+): Promise<EnrichedSkill[]> {
+  const lock = await readSkillLock()
+  const skillMap = new Map<string, EnrichedSkill>()
+
+  // Scan each agent's global skills directory
+  for (const agent of Object.values(agents)) {
+    const skillsDir = agent.globalSkillsDir
+    try {
+      const entries = await fs.readdir(skillsDir, { withFileTypes: true })
+      for (const entry of entries) {
+        // Include both real directories and symlinks (skills are often symlinked)
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+
+        const skillDirPath = path.join(skillsDir, entry.name)
+        const skillMdPath = path.join(skillDirPath, SKILL_MD)
+        try {
+          const raw = await fs.readFile(skillMdPath, "utf-8")
+          const { data: frontmatter } = matter(raw)
+          const skillName = entry.name
+          const canonicalPath = await fs.realpath(skillDirPath).catch(() => skillDirPath)
+          const scope = getScopeForPath(canonicalPath)
+          const supportingFiles = await listSupportingFiles(canonicalPath)
+
+          const existing = skillMap.get(canonicalPath)
+          if (existing) {
+            // Skill already seen from another agent - add this agent
+            if (!existing.agents.includes(agent.name)) {
+              existing.agents.push(agent.name)
+            }
+          } else {
+            skillMap.set(canonicalPath, {
+              name: skillName,
+              description:
+                (frontmatter.description as string) ??
+                extractFirstLine(raw),
+              filePath: skillMdPath,
+              canonicalPath,
+              agents: [agent.name],
+              scope,
+              projectName:
+                scope === "project" ? getProjectNameForPath(canonicalPath) : null,
+              hasSupportingFiles: supportingFiles.length > 0,
+              supportingFiles,
+              metadata: frontmatter as Record<string, unknown>,
+              lock: lock.skills[skillName],
+            })
+          }
+        } catch {
+          // SKILL.md not found or unreadable in this directory - skip
+        }
+      }
+    } catch {
+      // Agent skills directory doesn't exist - skip
+    }
+  }
+
+  const customScanPaths = settings.get<string[]>("scan.customPaths", [])
+  for (const customPath of customScanPaths) {
+    const resolvedRoot = path.resolve(customPath.replace(/^~(?=$|\/|\\)/, home))
+    const collected = await collectCustomSkills(resolvedRoot, lock)
+    for (const skill of collected) {
+      if (!skillMap.has(skill.canonicalPath)) {
+        skillMap.set(skill.canonicalPath, skill)
+      }
+    }
+  }
+
+  return Array.from(skillMap.values()).sort((a, b) =>
+    a.name.localeCompare(b.name)
+  )
+}
+
 async function collectCustomSkills(
   rootPath: string,
   lock: SkillLockFile,

package/src/db/migrations.ts

@@ -50,6 +50,26 @@ const MIGRATIONS: Migration[] = [
       INSERT OR IGNORE INTO schema_version VALUES (1);
     `,
   },
+  {
+    version: 2,
+    up: `
+      CREATE TABLE IF NOT EXISTS cached_skills (
+        canonical_path TEXT PRIMARY KEY,
+        folder_name TEXT NOT NULL,
+        name TEXT NOT NULL,
+        description TEXT NOT NULL DEFAULT '',
+        agents TEXT NOT NULL DEFAULT '[]',
+        agent_short_codes TEXT NOT NULL DEFAULT '[]',
+        scope TEXT NOT NULL DEFAULT 'global',
+        source TEXT,
+        source_type TEXT,
+        file_mod_time TEXT NOT NULL,
+        scanned_at TEXT NOT NULL
+      );
+
+      INSERT OR IGNORE INTO schema_version VALUES (2);
+    `,
+  },
 ]
 
 function getCurrentVersion(db: Database): number {

package/src/db/skills-cache.ts

@@ -0,0 +1,89 @@
+import type { Database } from "bun:sqlite"
+import type { AgentType, SourceType } from "../../../cli/src/types.js"
+
+export interface CachedSkill {
+  canonicalPath: string
+  folderName: string
+  name: string
+  description: string
+  agents: AgentType[]
+  agentShortCodes: string[]
+  scope: "global" | "project" | "custom"
+  source: string | null
+  sourceType: SourceType | null
+  fileModTime: string
+  scannedAt: string
+}
+
+interface CachedSkillRow {
+  canonical_path: string
+  folder_name: string
+  name: string
+  description: string
+  agents: string
+  agent_short_codes: string
+  scope: string
+  source: string | null
+  source_type: string | null
+  file_mod_time: string
+  scanned_at: string
+}
+
+function rowToSkill(row: CachedSkillRow): CachedSkill {
+  return {
+    canonicalPath: row.canonical_path,
+    folderName: row.folder_name,
+    name: row.name,
+    description: row.description,
+    agents: JSON.parse(row.agents) as AgentType[],
+    agentShortCodes: JSON.parse(row.agent_short_codes) as string[],
+    scope: row.scope as CachedSkill["scope"],
+    source: row.source,
+    sourceType: row.source_type as SourceType | null,
+    fileModTime: row.file_mod_time,
+    scannedAt: row.scanned_at,
+  }
+}
+
+export function loadCachedSkills(db: Database): CachedSkill[] {
+  const rows = db
+    .query("SELECT * FROM cached_skills ORDER BY name ASC")
+    .all() as CachedSkillRow[]
+  return rows.map(rowToSkill)
+}
+
+export function saveCachedSkills(db: Database, skills: CachedSkill[]): void {
+  const insert = db.query(
+    `INSERT OR REPLACE INTO cached_skills
+       (canonical_path, folder_name, name, description, agents, agent_short_codes, scope, source, source_type, file_mod_time, scanned_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  )
+
+  db.exec("BEGIN TRANSACTION")
+  try {
+    db.exec("DELETE FROM cached_skills")
+    for (const skill of skills) {
+      insert.run(
+        skill.canonicalPath,
+        skill.folderName,
+        skill.name,
+        skill.description,
+        JSON.stringify(skill.agents),
+        JSON.stringify(skill.agentShortCodes),
+        skill.scope,
+        skill.source,
+        skill.sourceType,
+        skill.fileModTime,
+        skill.scannedAt,
+      )
+    }
+    db.exec("COMMIT")
+  } catch (err) {
+    db.exec("ROLLBACK")
+    throw err
+  }
+}
+
+export function clearSkillsCache(db: Database): void {
+  db.exec("DELETE FROM cached_skills")
+}