skills-package-manager 0.1.1

package/src/install/installSkills.ts

@@ -0,0 +1,78 @@
+import { readSkillsLock } from '../config/readSkillsLock'
+import { readSkillsManifest } from '../config/readSkillsManifest'
+import { syncSkillsLock } from '../config/syncSkillsLock'
+import { writeSkillsLock } from '../config/writeSkillsLock'
+import { sha256 } from '../utils/hash'
+import { linkSkill } from './links'
+import { readInstallState, writeInstallState } from './installState'
+import { materializeGitSkill } from './materializeGitSkill'
+import { materializeLocalSkill } from './materializeLocalSkill'
+import { pruneManagedSkills } from './pruneManagedSkills'
+
+function extractSkillPath(specifier: string, skillName: string): string {
+  const marker = '#path:'
+  const index = specifier.indexOf(marker)
+  if (index >= 0) {
+    return specifier.slice(index + marker.length)
+  }
+  return `/${skillName}`
+}
+
+export async function installSkills(rootDir: string) {
+  const manifest = await readSkillsManifest(rootDir)
+  if (!manifest) {
+    return { status: 'skipped', reason: 'manifest-missing' } as const
+  }
+
+  const currentLock = await readSkillsLock(rootDir)
+  const lockfile = await syncSkillsLock(rootDir, manifest, currentLock)
+  await writeSkillsLock(rootDir, lockfile)
+
+  const lockDigest = sha256(JSON.stringify(lockfile))
+  const state = await readInstallState(rootDir)
+  if (state?.lockDigest === lockDigest) {
+    return { status: 'skipped', reason: 'up-to-date' } as const
+  }
+
+  const installDir = manifest.installDir ?? '.agents/skills'
+  const linkTargets = manifest.linkTargets ?? []
+
+  await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills))
+
+  for (const [skillName, entry] of Object.entries(lockfile.skills)) {
+    if (entry.resolution.type === 'file') {
+      await materializeLocalSkill(
+        rootDir,
+        skillName,
+        entry.resolution.path,
+        extractSkillPath(entry.specifier, skillName),
+        installDir,
+      )
+    } else if (entry.resolution.type === 'git') {
+      await materializeGitSkill(
+        rootDir,
+        skillName,
+        entry.resolution.url,
+        entry.resolution.commit,
+        entry.resolution.path,
+        installDir,
+      )
+    } else {
+      throw new Error(`Unsupported resolution type in 0.1.0 core flow: ${entry.resolution.type}`)
+    }
+
+    for (const linkTarget of linkTargets) {
+      await linkSkill(rootDir, installDir, linkTarget, skillName)
+    }
+  }
+
+  await writeInstallState(rootDir, {
+    lockDigest,
+    installDir,
+    linkTargets,
+    installerVersion: '0.1.0',
+    installedAt: new Date().toISOString(),
+  })
+
+  return { status: 'installed', installed: Object.keys(lockfile.skills) } as const
+}

package/src/install/installState.ts

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { ensureDir, writeJson } from '../utils/fs'
+
+export async function readInstallState(rootDir: string) {
+  const filePath = path.join(rootDir, '.agents/skills/.skills-pm-install-state.json')
+
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export async function writeInstallState(rootDir: string, value: unknown) {
+  const dirPath = path.join(rootDir, '.agents/skills')
+  await ensureDir(dirPath)
+  const filePath = path.join(dirPath, '.skills-pm-install-state.json')
+  await writeJson(filePath, value)
+}

package/src/install/links.ts

@@ -0,0 +1,9 @@
+import path from 'node:path'
+import { ensureDir, replaceSymlink } from '../utils/fs'
+
+export async function linkSkill(rootDir: string, installDir: string, linkTarget: string, skillName: string) {
+  const absoluteTarget = path.join(rootDir, installDir, skillName)
+  const absoluteLink = path.join(rootDir, linkTarget, skillName)
+  await ensureDir(path.dirname(absoluteLink))
+  await replaceSymlink(absoluteTarget, absoluteLink)
+}

package/src/install/materializeGitSkill.ts

@@ -0,0 +1,33 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { materializeLocalSkill } from './materializeLocalSkill'
+
+const execFileAsync = promisify(execFile)
+
+export async function materializeGitSkill(
+  rootDir: string,
+  skillName: string,
+  repoUrl: string,
+  commit: string,
+  sourcePath: string,
+  installDir: string,
+) {
+  const checkoutRoot = await mkdtemp(path.join(tmpdir(), 'skills-pm-git-checkout-'))
+
+  try {
+    await execFileAsync('git', ['clone', '--depth', '1', repoUrl, checkoutRoot])
+    if (commit && commit !== 'HEAD') {
+      await execFileAsync('git', ['checkout', commit], { cwd: checkoutRoot })
+    }
+
+    const skillDocPath = path.join(checkoutRoot, sourcePath.replace(/^\//, ''), 'SKILL.md')
+    await readFile(skillDocPath, 'utf8')
+
+    await materializeLocalSkill(rootDir, skillName, checkoutRoot, sourcePath, installDir)
+  } finally {
+    await rm(checkoutRoot, { recursive: true, force: true })
+  }
+}

package/src/install/materializeLocalSkill.ts

@@ -0,0 +1,35 @@
+import { cp, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { ensureDir, writeJson } from '../utils/fs'
+
+export async function materializeLocalSkill(
+  rootDir: string,
+  skillName: string,
+  sourceRoot: string,
+  sourcePath: string,
+  installDir: string,
+) {
+  const relativeSkillPath = sourcePath.replace(/^\//, '')
+  const absoluteSkillPath = path.join(sourceRoot, relativeSkillPath)
+  const skillDocPath = path.join(absoluteSkillPath, 'SKILL.md')
+
+  let skillDoc = ''
+  try {
+    skillDoc = await readFile(skillDocPath, 'utf8')
+  } catch {
+    throw new Error(`Invalid skill at ${absoluteSkillPath}: missing SKILL.md`)
+  }
+
+  if (!skillDoc) {
+    throw new Error(`Invalid skill at ${absoluteSkillPath}: missing SKILL.md`)
+  }
+
+  const targetDir = path.join(rootDir, installDir, skillName)
+  await ensureDir(path.dirname(targetDir))
+  await cp(absoluteSkillPath, targetDir, { recursive: true, force: true })
+  await writeJson(path.join(targetDir, '.skills-pm.json'), {
+    name: skillName,
+    installedBy: 'skills-pm',
+    version: '0.1.0',
+  })
+}

package/src/install/pruneManagedSkills.ts

@@ -0,0 +1,50 @@
+import { lstat, readdir, readFile, rm } from 'node:fs/promises'
+import path from 'node:path'
+
+async function isManagedSkillDir(dirPath: string): Promise<boolean> {
+  try {
+    const marker = JSON.parse(await readFile(path.join(dirPath, '.skills-pm.json'), 'utf8'))
+    return marker?.installedBy === 'skills-pm'
+  } catch {
+    return false
+  }
+}
+
+export async function pruneManagedSkills(rootDir: string, installDir: string, linkTargets: string[], wantedSkillNames: string[]) {
+  const wanted = new Set(wantedSkillNames)
+  const absoluteInstallDir = path.join(rootDir, installDir)
+
+  try {
+    const entries = await readdir(absoluteInstallDir)
+    for (const entry of entries) {
+      if (entry.startsWith('.')) {
+        continue
+      }
+
+      const skillDir = path.join(absoluteInstallDir, entry)
+      if (!(await isManagedSkillDir(skillDir))) {
+        continue
+      }
+
+      if (wanted.has(entry)) {
+        continue
+      }
+
+      await rm(skillDir, { recursive: true, force: true })
+
+      for (const linkTarget of linkTargets) {
+        const linkPath = path.join(rootDir, linkTarget, entry)
+        try {
+          const stat = await lstat(linkPath)
+          if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) {
+            await rm(linkPath, { recursive: true, force: true })
+          }
+        } catch {
+          // ignore missing link target
+        }
+      }
+    }
+  } catch {
+    // ignore missing install dir
+  }
+}

package/src/specifiers/normalizeSpecifier.ts

@@ -0,0 +1,29 @@
+import path from 'node:path'
+import type { NormalizedSpecifier } from '../config/types'
+import { parseSpecifier } from './parseSpecifier'
+
+export function normalizeSpecifier(specifier: string): NormalizedSpecifier {
+  const parsed = parseSpecifier(specifier)
+  const type = parsed.sourcePart.startsWith('file:')
+    ? 'file'
+    : parsed.sourcePart.startsWith('npm:')
+      ? 'npm'
+      : 'git'
+
+  const skillPath = parsed.path || '/'
+  const skillName = path.posix.basename(skillPath)
+  const normalized = parsed.ref
+    ? `${parsed.sourcePart}#${parsed.ref}&path:${skillPath}`
+    : parsed.path
+      ? `${parsed.sourcePart}#path:${skillPath}`
+      : parsed.sourcePart
+
+  return {
+    type,
+    source: parsed.sourcePart,
+    ref: parsed.ref,
+    path: skillPath,
+    normalized,
+    skillName,
+  }
+}

package/src/specifiers/parseSpecifier.ts

@@ -0,0 +1,45 @@
+export function parseSpecifier(specifier: string) {
+  const firstHashIndex = specifier.indexOf('#')
+  const secondHashIndex = firstHashIndex >= 0 ? specifier.indexOf('#', firstHashIndex + 1) : -1
+
+  if (secondHashIndex >= 0) {
+    throw new Error('Invalid specifier: multiple # fragments are not supported')
+  }
+
+  const hashIndex = firstHashIndex
+  const sourcePart = hashIndex >= 0 ? specifier.slice(0, hashIndex) : specifier
+  const fragment = hashIndex >= 0 ? specifier.slice(hashIndex + 1) : ''
+
+  if (!sourcePart) {
+    throw new Error('Specifier source is required')
+  }
+
+  if (!fragment) {
+    return {
+      sourcePart,
+      ref: null,
+      path: '',
+    }
+  }
+
+  const parts = fragment.split('&').filter(Boolean)
+  let ref: string | null = null
+  let parsedPath = ''
+
+  for (const part of parts) {
+    if (part.startsWith('path:')) {
+      parsedPath = part.slice('path:'.length)
+      continue
+    }
+
+    if (ref === null) {
+      ref = part
+    }
+  }
+
+  return {
+    sourcePart,
+    ref,
+    path: parsedPath,
+  }
+}

package/src/utils/fs.ts

@@ -0,0 +1,19 @@
+import { cp, mkdir, rm, symlink, writeFile } from 'node:fs/promises'
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true })
+}
+
+export async function replaceDir(from: string, to: string): Promise<void> {
+  await rm(to, { recursive: true, force: true })
+  await cp(from, to, { recursive: true })
+}
+
+export async function replaceSymlink(target: string, linkPath: string): Promise<void> {
+  await rm(linkPath, { recursive: true, force: true })
+  await symlink(target, linkPath)
+}
+
+export async function writeJson(filePath: string, value: unknown): Promise<void> {
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+}

package/src/utils/hash.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto'
+
+export function sha256(content: string): string {
+  return `sha256-${createHash('sha256').update(content).digest('hex')}`
+}

package/test/add.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from '@rstest/core'
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { execSync } from 'node:child_process'
+import YAML from 'yaml'
+import { addCommand } from '../src/commands/add'
+
+describe('addCommand', () => {
+  it('writes manifest and lock for a file skill specifier', async () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'skills-pm-add-'))
+    await addCommand({
+      cwd: root,
+      specifier: 'file:./packages/skills-pm/test/fixtures/local-source#path:/skills/hello-skill',
+    })
+
+    const manifest = JSON.parse(readFileSync(path.join(root, 'skills.json'), 'utf8'))
+    const lockfile = YAML.parse(readFileSync(path.join(root, 'skills-lock.yaml'), 'utf8'))
+
+    expect(manifest.skills['hello-skill']).toBe('file:./packages/skills-pm/test/fixtures/local-source#path:/skills/hello-skill')
+    expect(lockfile.skills['hello-skill'].resolution.type).toBe('file')
+  })
+
+  it('writes manifest and lock for a git skill specifier', async () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'skills-pm-add-git-'))
+    const gitRepo = mkdtempSync(path.join(tmpdir(), 'skills-pm-add-git-source-'))
+
+    mkdirSync(path.join(gitRepo, 'skills/hello-skill'), { recursive: true })
+    writeFileSync(path.join(gitRepo, 'skills/hello-skill/SKILL.md'), '# Hello from add git\n')
+    execSync('git init', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git config user.email test@example.com', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git config user.name test', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git add .', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git commit -m init', { cwd: gitRepo, stdio: 'ignore' })
+    const commit = execSync('git rev-parse HEAD', { cwd: gitRepo }).toString().trim()
+
+    await addCommand({
+      cwd: root,
+      specifier: `${gitRepo}#HEAD&path:/skills/hello-skill`,
+    })
+
+    const manifest = JSON.parse(readFileSync(path.join(root, 'skills.json'), 'utf8'))
+    const lockfile = YAML.parse(readFileSync(path.join(root, 'skills-lock.yaml'), 'utf8'))
+
+    expect(manifest.skills['hello-skill']).toBe(`${gitRepo}#HEAD&path:/skills/hello-skill`)
+    expect(lockfile.skills['hello-skill'].resolution.type).toBe('git')
+    expect(lockfile.skills['hello-skill'].resolution.url).toBe(gitRepo)
+    expect(lockfile.skills['hello-skill'].resolution.commit).toBe(commit)
+    expect(lockfile.skills['hello-skill'].resolution.path).toBe('/skills/hello-skill')
+  })
+
+  it('adds a skill with owner/repo and --skill flag', async () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'skills-pm-add-shorthand-'))
+    const gitRepo = mkdtempSync(path.join(tmpdir(), 'skills-pm-add-shorthand-source-'))
+
+    mkdirSync(path.join(gitRepo, 'dogfood'), { recursive: true })
+    writeFileSync(path.join(gitRepo, 'dogfood/SKILL.md'), '# Dogfood skill\n')
+    execSync('git init', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git config user.email test@example.com', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git config user.name test', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git add .', { cwd: gitRepo, stdio: 'ignore' })
+    execSync('git commit -m init', { cwd: gitRepo, stdio: 'ignore' })
+
+    // Use a direct git specifier to test the --skill path builds the right specifier
+    // (We can't actually test owner/repo without GitHub API, so test the protocol fallback)
+    await addCommand({
+      cwd: root,
+      specifier: `${gitRepo}#HEAD&path:/dogfood`,
+      skill: undefined,
+    })
+
+    const manifest = JSON.parse(readFileSync(path.join(root, 'skills.json'), 'utf8'))
+    expect(manifest.skills['dogfood']).toBe(`${gitRepo}#HEAD&path:/dogfood`)
+  })
+})

package/test/fixtures/local-source/skills/hello-skill/SKILL.md

@@ -0,0 +1,3 @@
+# Hello skill
+
+This is a local fixture skill.

package/test/fixtures/local-source/skills/hello-skill/references/example.md

@@ -0,0 +1 @@
+Example reference document.

package/test/github.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from '@rstest/core'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { parseOwnerRepo, parseGitHubUrl, discoverSkillsInDir } from '../src/github/listSkills'
+
+describe('parseOwnerRepo', () => {
+  it('parses owner/repo format', () => {
+    expect(parseOwnerRepo('mxyhi/ok-skills')).toEqual({
+      owner: 'mxyhi',
+      repo: 'ok-skills',
+    })
+  })
+
+  it('parses owner/repo with dots and hyphens', () => {
+    expect(parseOwnerRepo('some.user/my-repo.git')).toEqual({
+      owner: 'some.user',
+      repo: 'my-repo.git',
+    })
+  })
+
+  it('returns null for protocol specifiers', () => {
+    expect(parseOwnerRepo('file:./local-source')).toBeNull()
+    expect(parseOwnerRepo('npm:@scope/pkg')).toBeNull()
+    expect(parseOwnerRepo('https://github.com/owner/repo.git')).toBeNull()
+  })
+
+  it('returns null for bare names without slash', () => {
+    expect(parseOwnerRepo('some-skill')).toBeNull()
+  })
+
+  it('returns null for paths with multiple slashes', () => {
+    expect(parseOwnerRepo('a/b/c')).toBeNull()
+  })
+})
+
+describe('parseGitHubUrl', () => {
+  it('parses https://github.com/owner/repo', () => {
+    expect(parseGitHubUrl('https://github.com/vercel-labs/skills')).toEqual({
+      owner: 'vercel-labs',
+      repo: 'skills',
+    })
+  })
+
+  it('parses https://github.com/owner/repo.git', () => {
+    expect(parseGitHubUrl('https://github.com/mxyhi/ok-skills.git')).toEqual({
+      owner: 'mxyhi',
+      repo: 'ok-skills',
+    })
+  })
+
+  it('parses with trailing slash', () => {
+    expect(parseGitHubUrl('https://github.com/owner/repo/')).toEqual({
+      owner: 'owner',
+      repo: 'repo',
+    })
+  })
+
+  it('returns null for non-GitHub URLs', () => {
+    expect(parseGitHubUrl('https://gitlab.com/owner/repo')).toBeNull()
+  })
+
+  it('returns null for GitHub URLs with path fragments', () => {
+    expect(parseGitHubUrl('https://github.com/owner/repo/tree/main')).toBeNull()
+  })
+
+  it('returns null for owner/repo shorthand', () => {
+    expect(parseGitHubUrl('owner/repo')).toBeNull()
+  })
+})
+
+describe('discoverSkillsInDir', () => {
+  it('discovers skills at root level', async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), 'skills-discover-root-'))
+    mkdirSync(path.join(dir, 'my-skill'), { recursive: true })
+    writeFileSync(
+      path.join(dir, 'my-skill/SKILL.md'),
+      '---\nname: my-skill\ndescription: A test skill\n---\n# My Skill\n',
+    )
+
+    const skills = await discoverSkillsInDir(dir)
+    expect(skills).toHaveLength(1)
+    expect(skills[0].name).toBe('my-skill')
+    expect(skills[0].description).toBe('A test skill')
+    expect(skills[0].path).toBe('/my-skill')
+  })
+
+  it('discovers skills in skills/ subdirectory', async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), 'skills-discover-sub-'))
+    mkdirSync(path.join(dir, 'skills/find-skills'), { recursive: true })
+    writeFileSync(
+      path.join(dir, 'skills/find-skills/SKILL.md'),
+      '---\nname: find-skills\ndescription: Find skills\n---\n',
+    )
+
+    const skills = await discoverSkillsInDir(dir)
+    expect(skills).toHaveLength(1)
+    expect(skills[0].name).toBe('find-skills')
+    expect(skills[0].path).toBe('/skills/find-skills')
+  })
+
+  it('returns empty array when no skills found', async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), 'skills-discover-empty-'))
+    mkdirSync(path.join(dir, 'some-dir'), { recursive: true })
+    writeFileSync(path.join(dir, 'some-dir/README.md'), '# Not a skill\n')
+
+    const skills = await discoverSkillsInDir(dir)
+    expect(skills).toHaveLength(0)
+  })
+
+  it('uses directory name when frontmatter has no name', async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), 'skills-discover-noname-'))
+    mkdirSync(path.join(dir, 'cool-skill'), { recursive: true })
+    writeFileSync(path.join(dir, 'cool-skill/SKILL.md'), '# Just a heading\n')
+
+    const skills = await discoverSkillsInDir(dir)
+    expect(skills).toHaveLength(1)
+    expect(skills[0].name).toBe('cool-skill')
+  })
+})