refactor install logic and add tests for incremental updates

Author: LadyBluenotes

packages/installer/package.json

@@ -8,7 +8,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/cli.ts"
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run"
   },
   "devDependencies": {
     "typescript": "^5.5.0",

packages/installer/src/cli.ts

@@ -35,6 +35,17 @@ type Manifest = {
   agents: Array<{ id: string; path: string }>
 }
 
+type InstalledSkill = {
+  lib: string
+  version: string
+  signature: string | null
+}
+
+type SkillsLock = {
+  schema: number
+  installed: Record<string, InstalledSkill>
+}
+
 function arg(name: string) {
   const idx = process.argv.indexOf(`--${name}`)
   return idx >= 0 ? process.argv[idx + 1] : undefined
@@ -237,14 +248,14 @@ function resolveExactFromPackageJson(
   )
 }
 
-async function main() {
-  const cmd = process.argv[2]
-  if (cmd !== 'install') throw new Error(`Unknown command: ${cmd}`)
-
-  const projectArg = arg('project')
-  if (!projectArg) throw new Error('--project is required')
+type InstallOptions = {
+  projectDir: string
+  repoRoot: string
+  buildMissing: boolean
+}
 
-  const projectDir = resolveProjectDir(projectArg)
+export async function installSkills(options: InstallOptions) {
+  const { projectDir, repoRoot, buildMissing } = options
 
   const pkgPath = path.join(projectDir, 'package.json')
   if (!fs.existsSync(pkgPath)) {
@@ -256,10 +267,6 @@ async function main() {
 
   const lock = readPnpmLock(projectDir)
 
-  const repoRoot = getRepoRootFromThisFile()
-
-  const buildMissing = hasFlag('build-missing')
-
   const manifestPath = path.join(repoRoot, 'registry', 'manifest.json')
   if (!fs.existsSync(manifestPath)) {
     throw new Error(
@@ -292,19 +299,11 @@ async function main() {
   ensureDir(destSkillsDir)
 
   const outLockPath = path.join(projectDir, 'skills.lock.json')
-  const prevLock = readJsonIfExists<any>(outLockPath)
+  const prevLock = readJsonIfExists<SkillsLock | Record<string, any>>(
+    outLockPath,
+  )
   const prevInstalled: Record<string, any> = prevLock?.installed ?? {}
 
-  if (
-    buildMissing &&
-    prevLock?.registry?.type &&
-    prevLock.registry.type !== 'local'
-  ) {
-    throw new Error(
-      `--build-missing is only supported for local registries (found: ${prevLock.registry.type}).`,
-    )
-  }
-
   // Always install the top-level tanstack agent if present
   const tanstackAgent = manifest.agents.find((a) => a.id === 'tanstack')
   if (tanstackAgent) {
@@ -417,30 +416,40 @@ async function main() {
       lib: libId,
       version: exactVersion,
       signature,
-      agent_path: agentPath,
-      skill_dir: skillDirPath,
-      version_from: versionPkg,
     }
   }
 
   // write lockfile
-  fs.writeFileSync(
-    outLockPath,
-    JSON.stringify(
-      {
-        schema: 1,
-        registry: { type: 'local', repoRoot },
-        installed,
-      },
-      null,
-      2,
-    ) + '\n',
-  )
+  const lockfile: SkillsLock = {
+    schema: 1,
+    installed,
+  }
+  fs.writeFileSync(outLockPath, JSON.stringify(lockfile, null, 2) + '\n')
 
   console.log(`Installed: ${libs.join(', ') || '(none)'}`)
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : error)
-  process.exit(1)
-})
+async function main() {
+  const cmd = process.argv[2]
+  if (cmd !== 'install') throw new Error(`Unknown command: ${cmd}`)
+
+  const projectArg = arg('project')
+  if (!projectArg) throw new Error('--project is required')
+
+  const projectDir = resolveProjectDir(projectArg)
+  const repoRoot = getRepoRootFromThisFile()
+  const buildMissing = hasFlag('build-missing')
+
+  await installSkills({ projectDir, repoRoot, buildMissing })
+}
+
+const isDirectRun =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error)
+    process.exit(1)
+  })
+}

packages/installer/test/install.test.ts

@@ -0,0 +1,150 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, test } from 'vitest'
+import { installSkills } from '../src/cli.js'
+
+function writeJson(filePath: string, data: unknown) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n')
+}
+
+function writeFile(filePath: string, content: string) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content)
+}
+
+function createRepoRoot(baseDir: string, signature: string, content: string) {
+  const repoRoot = path.join(baseDir, 'repo')
+  const catalog = `schema: 1
+libraries:
+  query:
+    id: query
+    packages:
+      - "@tanstack/query"
+    version_from:
+      - "@tanstack/query"
+`
+
+  writeFile(path.join(repoRoot, 'catalog.yaml'), catalog)
+
+  const skillDir = path.join(repoRoot, 'registry', 'skills', 'query', '5.90.21')
+
+  writeFile(path.join(skillDir, 'skill.md'), content)
+  writeFile(path.join(skillDir, 'agent.md'), `# Query\n${content}\n`)
+
+  writeJson(path.join(repoRoot, 'registry', 'manifest.json'), {
+    schema: 1,
+    skills: [
+      {
+        lib: 'query',
+        version: '5.90.21',
+        signature,
+        skill_dir: 'registry/skills/query/5.90.21',
+        agent_md: 'registry/skills/query/5.90.21/agent.md',
+      },
+    ],
+    agents: [],
+  })
+
+  return repoRoot
+}
+
+function createProject(baseDir: string) {
+  const projectDir = path.join(baseDir, 'project')
+  writeJson(path.join(projectDir, 'package.json'), {
+    name: 'demo',
+    version: '0.0.0',
+    dependencies: {
+      '@tanstack/query': '5.90.21',
+    },
+  })
+  return projectDir
+}
+
+describe('installer incremental updates', () => {
+  test('unchanged registry is a no-op', async () => {
+    const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'installer-'))
+    const repoRoot = createRepoRoot(baseDir, 'sig-1', 'content-v1')
+    const projectDir = createProject(baseDir)
+
+    await installSkills({ projectDir, repoRoot, buildMissing: false })
+
+    const agentPath = path.join(
+      projectDir,
+      '.agents',
+      'agents',
+      'tanstack-query.md',
+    )
+    const skillPath = path.join(
+      projectDir,
+      '.agents',
+      'skills',
+      'query',
+      'skill.md',
+    )
+
+    const agentStat = fs.statSync(agentPath)
+    const skillStat = fs.statSync(skillPath)
+
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    await installSkills({ projectDir, repoRoot, buildMissing: false })
+
+    expect(fs.statSync(agentPath).mtimeMs).toBe(agentStat.mtimeMs)
+    expect(fs.statSync(skillPath).mtimeMs).toBe(skillStat.mtimeMs)
+  })
+
+  test('changed signature triggers update', async () => {
+    const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'installer-'))
+    const repoRoot = createRepoRoot(baseDir, 'sig-1', 'content-v1')
+    const projectDir = createProject(baseDir)
+
+    await installSkills({ projectDir, repoRoot, buildMissing: false })
+
+    writeFile(
+      path.join(repoRoot, 'registry', 'skills', 'query', '5.90.21', 'skill.md'),
+      'content-v2',
+    )
+    writeFile(
+      path.join(repoRoot, 'registry', 'skills', 'query', '5.90.21', 'agent.md'),
+      '# Query\ncontent-v2\n',
+    )
+
+    writeJson(path.join(repoRoot, 'registry', 'manifest.json'), {
+      schema: 1,
+      skills: [
+        {
+          lib: 'query',
+          version: '5.90.21',
+          signature: 'sig-2',
+          skill_dir: 'registry/skills/query/5.90.21',
+          agent_md: 'registry/skills/query/5.90.21/agent.md',
+        },
+      ],
+      agents: [],
+    })
+
+    await installSkills({ projectDir, repoRoot, buildMissing: false })
+
+    const updatedSkill = fs.readFileSync(
+      path.join(projectDir, '.agents', 'skills', 'query', 'skill.md'),
+      'utf8',
+    )
+    const updatedLock = JSON.parse(
+      fs.readFileSync(path.join(projectDir, 'skills.lock.json'), 'utf8'),
+    )
+
+    expect(updatedSkill).toBe('content-v2')
+    expect(updatedLock).toEqual({
+      schema: 1,
+      installed: {
+        query: {
+          lib: 'query',
+          version: '5.90.21',
+          signature: 'sig-2',
+        },
+      },
+    })
+  })
+})

packages/installer/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+})