@lythos/cold-pool 0.16.0 → 0.17.0

package/README.md

@@ -15,10 +15,10 @@ deck / curator / arena consume it instead of running `git clone` themselves.
 
 ```bash
 # Scan cold pool for unreferenced repos
-bunx @lythos/cold-pool@0.16.0 prune [--yes] [--dry-run]
+bunx @lythos/cold-pool@0.17.0 prune [--yes] [--dry-run]
 
 # Validate lock file against cold pool
-bunx @lythos/cold-pool@0.16.0 validate [--lock ./skill-deck.lock]
+bunx @lythos/cold-pool@0.17.0 validate [--lock ./skill-deck.lock]
 ```
 
 ## Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Cold pool service layer — dedicated resource holder for skill repositories with intent/plan/execute primitives. Single owner of git side-effects; consumed by deck/curator/arena.",
   "keywords": [
     "ai-agent",
@@ -42,7 +42,7 @@
   },
   "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-cold-pool#readme",
   "dependencies": {
-    "@lythos/infra": "^0.16.0",
+    "@lythos/infra": "^0.17.0",
     "simple-git": "^3.36.0"
   },
   "engines": {

package/src/cold-pool.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, it } from 'bun:test'
 import { mkdirSync, mkdtempSync, writeFileSync, existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -9,12 +9,12 @@ function dir(relPath: string): DirEntry { return { relPath, isDirectory: true }
 function file(relPath: string): DirEntry { return { relPath, isDirectory: false } }
 
 describe('ColdPool — constructor', () => {
-  test('default path when none given', () => {
+  it('default path when none given', () => {
     const pool = new ColdPool()
     expect(pool.path).toBe(DEFAULT_COLD_POOL_PATH)
   })
 
-  test('custom path is stored verbatim', () => {
+  it('custom path is stored verbatim', () => {
     const pool = new ColdPool('/tmp/custom-pool')
     expect(pool.path).toBe('/tmp/custom-pool')
   })
@@ -23,18 +23,18 @@ describe('ColdPool — constructor', () => {
 describe('ColdPool.resolveDir — pure path computation', () => {
   const pool = new ColdPool('/cold')
 
-  test('host/owner/repo', () => {
+  it('host/owner/repo', () => {
     const loc = parseLocator('github.com/anthropics/skills')!
     expect(pool.resolveDir(loc)).toBe('/cold/github.com/anthropics/skills')
   })
 
-  test('host/owner/repo/skill — skill subpath does NOT extend the dir', () => {
+  it('host/owner/repo/skill — skill subpath does NOT extend the dir', () => {
     // resolveDir returns repo dir, not skill dir. Skill subpath is for findSkillDir later.
     const loc = parseLocator('github.com/anthropics/skills/skills/pdf')!
     expect(pool.resolveDir(loc)).toBe('/cold/github.com/anthropics/skills')
   })
 
-  test('localhost form — uniform <pool>/<host>/<owner>/<repo>, no special-case', () => {
+  it('localhost form — uniform <pool>/<host>/<owner>/<repo>, no special-case', () => {
     const loc = parseLocator('localhost/me/my-skill')!
     expect(pool.resolveDir(loc)).toBe('/cold/localhost/me/my-skill')
   })
@@ -56,22 +56,22 @@ describe('ColdPool — fs-backed read accessors', () => {
 
   const pool = new ColdPool(root)
 
-  test('has() returns true for existing repo', () => {
+  it('has() returns true for existing repo', () => {
     const loc = parseLocator('github.com/owner/repo-a')!
     expect(pool.has(loc)).toBe(true)
   })
 
-  test('has() returns false for missing repo', () => {
+  it('has() returns false for missing repo', () => {
     const loc = parseLocator('github.com/owner/missing')!
     expect(pool.has(loc)).toBe(false)
   })
 
-  test('has() works for localhost form (uniform <host>/<owner>/<repo>)', () => {
+  it('has() works for localhost form (uniform <host>/<owner>/<repo>)', () => {
     const loc = parseLocator('localhost/me/skill-x')!
     expect(pool.has(loc)).toBe(true)
   })
 
-  test('list() enumerates uniform host/owner/repo across all hosts, skips hidden', () => {
+  it('list() enumerates uniform host/owner/repo across all hosts, skips hidden', () => {
     const entries = pool.list().sort()
     expect(entries).toEqual([
       join(root, 'github.com/owner/repo-a'),
@@ -80,7 +80,7 @@ describe('ColdPool — fs-backed read accessors', () => {
     ].sort())
   })
 
-  test('list() includes legacy drift entries (depth-2 SKILL.md, missing repo level) for cleanup awareness', () => {
+  it('list() includes legacy drift entries (depth-2 SKILL.md, missing repo level) for cleanup awareness', () => {
     const driftRoot = mkdtempSync(join(tmpdir(), 'cold-pool-drift-'))
     mkdirSync(join(driftRoot, 'github.com/o/r'), { recursive: true })
     mkdirSync(join(driftRoot, 'localhost/me/canonical'), { recursive: true })
@@ -99,7 +99,7 @@ describe('ColdPool — fs-backed read accessors', () => {
     expect(entries).toContain(join(driftRoot, 'localhost/legacy-name'))
   })
 
-  test('list() returns [] when path does not exist', () => {
+  it('list() returns [] when path does not exist', () => {
     const empty = new ColdPool('/no/such/path')
     expect(empty.list()).toEqual([])
   })
@@ -108,7 +108,7 @@ describe('ColdPool — fs-backed read accessors', () => {
 describe('buildListPlan — pure classification (no IO)', () => {
   const root = '/pool'
 
-  test('canonical 3-segment: host/owner/repo', () => {
+  it('canonical 3-segment: host/owner/repo', () => {
     const entries: DirEntry[] = [
       dir('github.com'),
       dir('github.com/owner'),
@@ -121,7 +121,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
     ])
   })
 
-  test('skips hidden dirs', () => {
+  it('skips hidden dirs', () => {
     const entries: DirEntry[] = [
       dir('.git'),
       dir('github.com'),
@@ -136,7 +136,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
     ])
   })
 
-  test('legacy depth-1: host/SKILL.md (missing owner+repo)', () => {
+  it('legacy depth-1: host/SKILL.md (missing owner+repo)', () => {
     const entries: DirEntry[] = [
       dir('legacy-skill'),
       file('legacy-skill/SKILL.md'),
@@ -147,7 +147,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
     ])
   })
 
-  test('legacy depth-2: localhost/name/SKILL.md (missing repo)', () => {
+  it('legacy depth-2: localhost/name/SKILL.md (missing repo)', () => {
     const entries: DirEntry[] = [
       dir('localhost'),
       dir('localhost/legacy-name'),
@@ -159,7 +159,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
     ])
   })
 
-  test('mixed canonical + legacy in same pool', () => {
+  it('mixed canonical + legacy in same pool', () => {
     const entries: DirEntry[] = [
       dir('github.com'),
       dir('github.com/owner'),
@@ -175,7 +175,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
     expect(plan.entries).toContainEqual({ path: '/pool/localhost/old-skill', kind: 'legacy-depth2' })
   })
 
-  test('multiple repos under same owner', () => {
+  it('multiple repos under same owner', () => {
     const entries: DirEntry[] = [
       dir('github.com'),
       dir('github.com/owner'),
@@ -191,7 +191,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
     expect(plan.entries.every(e => e.kind === 'canonical')).toBe(true)
   })
 
-  test('multiple hosts', () => {
+  it('multiple hosts', () => {
     const entries: DirEntry[] = [
       dir('github.com'),
       dir('github.com/a'),
@@ -210,11 +210,11 @@ describe('buildListPlan — pure classification (no IO)', () => {
     ])
   })
 
-  test('returns empty when root has no entries', () => {
+  it('returns empty when root has no entries', () => {
     expect(buildListPlan(root, []).entries).toEqual([])
   })
 
-  test('returns empty for hidden-only entries', () => {
+  it('returns empty for hidden-only entries', () => {
     const entries: DirEntry[] = [dir('.git'), dir('.hidden/.nested')]
     expect(buildListPlan(root, entries).entries).toEqual([])
   })
@@ -224,7 +224,7 @@ describe('ColdPool.metadata — MetadataDB integration', () => {
   const root = mkdtempSync(join(tmpdir(), 'cold-pool-meta-test-'))
   const pool = new ColdPool(root)
 
-  test('metadata is auto-created on first access (lazy-open)', () => {
+  it('metadata is auto-created on first access (lazy-open)', () => {
     expect(pool.metadata).toBeDefined()
     // Lazy-open: DB file is NOT created until first method call.
     expect(existsSync(join(root, '.cold-pool-meta.db'))).toBe(false)
@@ -233,7 +233,7 @@ describe('ColdPool.metadata — MetadataDB integration', () => {
     expect(existsSync(join(root, '.cold-pool-meta.db'))).toBe(true)
   })
 
-  test('metadata records survive round-trip', () => {
+  it('metadata records survive round-trip', () => {
     pool.metadata.recordRepoRef('github.com', 'lythos-labs', 'lythoskill', '9645fdb')
     expect(pool.metadata.getRepoRef('github.com', 'lythos-labs', 'lythoskill')).toBe('9645fdb')
   })

package/src/fetch-plan.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, it } from 'bun:test'
 import { mkdtempSync, mkdirSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -8,7 +8,7 @@ import { buildFetchPlan, executeFetchPlan } from './fetch-plan'
 import type { FetchIO } from './types'
 
 describe('buildFetchPlan', () => {
-  test('builds targetDir + cloneUrl from locator', () => {
+  it('builds targetDir + cloneUrl from locator', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('github.com/anthropics/skills/skills/pdf')!
     const plan = buildFetchPlan(pool, loc)
@@ -17,7 +17,7 @@ describe('buildFetchPlan', () => {
     expect(plan.alreadyExists).toBe(false)
   })
 
-  test('alreadyExists reflects fs presence', () => {
+  it('alreadyExists reflects fs presence', () => {
     const root = mkdtempSync(join(tmpdir(), 'fetch-plan-test-'))
     mkdirSync(join(root, 'github.com/owner/repo'), { recursive: true })
     const pool = new ColdPool(root)
@@ -26,7 +26,7 @@ describe('buildFetchPlan', () => {
     expect(plan.alreadyExists).toBe(true)
   })
 
-  test('localhost locator gets empty cloneUrl + uniform <host>/<owner>/<repo> path', () => {
+  it('localhost locator gets empty cloneUrl + uniform <host>/<owner>/<repo> path', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('localhost/me/my-skill')!
     const plan = buildFetchPlan(pool, loc)
@@ -34,7 +34,7 @@ describe('buildFetchPlan', () => {
     expect(plan.targetDir).toBe('/cold/localhost/me/my-skill')
   })
 
-  test('passes ref through', () => {
+  it('passes ref through', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('github.com/o/r')!
     const plan = buildFetchPlan(pool, loc, { ref: 'v1.2.3' })
@@ -43,7 +43,7 @@ describe('buildFetchPlan', () => {
 })
 
 describe('executeFetchPlan', () => {
-  test('alreadyExists path → already-present, no clone called', () => {
+  it('alreadyExists path → already-present, no clone called', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('github.com/o/r')!
     const plan = { ...buildFetchPlan(pool, loc), alreadyExists: true }
@@ -57,7 +57,7 @@ describe('executeFetchPlan', () => {
     expect(cloneCalls).toBe(0)
   })
 
-  test('clones when target absent', () => {
+  it('clones when target absent', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('github.com/o/r')!
     const plan = buildFetchPlan(pool, loc)
@@ -73,7 +73,7 @@ describe('executeFetchPlan', () => {
     expect(cloneArgs[0].dir).toBe('/cold/github.com/o/r')
   })
 
-  test('clone error → failed result with message', () => {
+  it('clone error → failed result with message', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('github.com/o/r')!
     const plan = buildFetchPlan(pool, loc)
@@ -86,7 +86,7 @@ describe('executeFetchPlan', () => {
     expect(result.message).toContain('boom')
   })
 
-  test('localhost locator refuses to fetch', () => {
+  it('localhost locator refuses to fetch', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('localhost/me/x')!
     const plan = buildFetchPlan(pool, loc)
@@ -101,7 +101,7 @@ describe('executeFetchPlan', () => {
     expect(cloneCalls).toBe(0)
   })
 
-  test('log IO is invoked', () => {
+  it('log IO is invoked', () => {
     const pool = new ColdPool('/cold')
     const loc = parseLocator('github.com/o/r')!
     const plan = buildFetchPlan(pool, loc)

package/src/git-hash.test.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { simpleGit } from 'simple-git'
-import { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd } from './git-hash.js'
+import { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd, parseTreeHash, computeSha256, buildSkillPath } from './git-hash.js'
 
 let repoDir: string
 let canGit = false
@@ -91,6 +91,63 @@ describe('getSkillBlobHash', () => {
   })
 })
 
+// ── Pure functions (L0 — no git, no fs) ─────────────────────────
+
+describe('parseTreeHash', () => {
+  it('extracts hash from ls-tree output', () => {
+    // Real git ls-tree output format: <mode> <type> <hash>\t<path>
+    const line = '100644 blob abc123def456789012345678901234567890abcd\tSKILL.md'
+    expect(parseTreeHash(line)).toBe('abc123def456789012345678901234567890abcd')
+  })
+
+  it('extracts tree hash from tree entry', () => {
+    const line = '040000 tree def456abc789012345678901234567890abcd123\tpdf'
+    expect(parseTreeHash(line)).toBe('def456abc789012345678901234567890abcd123')
+  })
+
+  it('handles output with leading/trailing whitespace', () => {
+    const line = '  100644 blob aaa111bbb222ccc333ddd444eee555fff666777888\tfile.md  '
+    expect(parseTreeHash(line)).toBe('aaa111bbb222ccc333ddd444eee555fff666777888')
+  })
+
+  it('throws on empty output', () => {
+    expect(() => parseTreeHash('')).toThrow('Empty ls-tree output')
+    expect(() => parseTreeHash('   ')).toThrow('Empty ls-tree output')
+  })
+
+  it('throws on unparseable output', () => {
+    expect(() => parseTreeHash('garbage')).toThrow('Could not parse tree hash')
+  })
+})
+
+describe('computeSha256', () => {
+  it('computes deterministic hash', () => {
+    expect(computeSha256('hello')).toBe(computeSha256('hello'))
+  })
+
+  it('produces 64-char hex string', () => {
+    const hash = computeSha256('test content')
+    expect(hash.length).toBe(64)
+    expect(/^[a-f0-9]{64}$/.test(hash)).toBe(true)
+  })
+
+  it('different content → different hash', () => {
+    expect(computeSha256('a')).not.toBe(computeSha256('b'))
+  })
+})
+
+describe('buildSkillPath', () => {
+  it('appends SKILL.md to subpath', () => {
+    expect(buildSkillPath('skills/pdf')).toBe('skills/pdf/SKILL.md')
+  })
+
+  it('returns just SKILL.md for empty subpath', () => {
+    expect(buildSkillPath('')).toBe('SKILL.md')
+  })
+})
+
+// ── IO functions (L1 — real git in temp repo) ───────────────────
+
 describe('getSkillTreeHash', () => {
   it('returns tree hash for subdirectory', async () => {
     if (!canGit) return

package/src/git-hash.ts

@@ -2,6 +2,29 @@ import { simpleGit, type SimpleGit } from 'simple-git'
 import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 
+// ── Pure functions (L0-testable, no git, no fs) ─────────────────
+
+/** Parse `git ls-tree` output line. Takes the third whitespace-separated field (the hash). */
+export function parseTreeHash(lsTreeOutput: string): string {
+  const trimmed = lsTreeOutput.trim()
+  if (!trimmed) throw new Error('Empty ls-tree output')
+  const hash = trimmed.split(/\s+/)[2]
+  if (!hash) throw new Error(`Could not parse tree hash from: ${trimmed}`)
+  return hash
+}
+
+/** Compute SHA-256 of raw content. Content-addressable, provider-agnostic. */
+export function computeSha256(content: string): string {
+  return createHash('sha256').update(content, 'utf-8').digest('hex')
+}
+
+/** Build the skill path for git blob/tree operations. */
+export function buildSkillPath(skillSubpath: string): string {
+  return skillSubpath ? `${skillSubpath}/SKILL.md` : 'SKILL.md'
+}
+
+// ── IO wrappers (thin — call git/fs, delegate to pure functions) ─
+
 function git(repoDir: string): SimpleGit {
   return simpleGit(repoDir)
 }
@@ -11,17 +34,14 @@ export async function getRepoHeadRef(repoDir: string): Promise<string> {
 }
 
 export async function getSkillBlobHash(repoDir: string, skillSubpath: string): Promise<string> {
-  const path = skillSubpath ? `${skillSubpath}/SKILL.md` : 'SKILL.md'
-  return (await git(repoDir).raw(['hash-object', path])).trim()
+  return (await git(repoDir).raw(['hash-object', buildSkillPath(skillSubpath)])).trim()
 }
 
 export function hashSkillMd(skillMdPath: string): string {
-  return createHash('sha256').update(readFileSync(skillMdPath, 'utf-8')).digest('hex')
+  return computeSha256(readFileSync(skillMdPath, 'utf-8'))
 }
 
 export async function getSkillTreeHash(repoDir: string, skillSubpath: string): Promise<string> {
   const output = (await git(repoDir).raw(['ls-tree', 'HEAD', skillSubpath || '.'])).trim()
-  const hash = output.split(/\s+/)[2]
-  if (!hash) throw new Error(`Could not parse tree hash from: ${output}`)
-  return hash
+  return parseTreeHash(output)
 }

package/src/git-io.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, beforeEach, afterEach } from 'bun:test'
+import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
 import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
@@ -26,23 +26,23 @@ describe('detectGitRoot', () => {
   const orphanDir = join(root, 'pool/orphan')
   mkdirSync(orphanDir, { recursive: true })
 
-  test('finds .git at the same dir', () => {
+  it('finds .git at the same dir', () => {
     const r = detectGitRoot(repoDir)
     expect(r.gitRoot).toBe(resolve(repoDir))
   })
 
-  test('walks up to find .git', () => {
+  it('walks up to find .git', () => {
     const r = detectGitRoot(subDir)
     expect(r.gitRoot).toBe(resolve(repoDir))
   })
 
-  test('returns not-found when no .git in walk', () => {
+  it('returns not-found when no .git in walk', () => {
     const r = detectGitRoot(orphanDir)
     expect(r.gitRoot).toBeNull()
     expect(r.reason).toBe('not-found')
   })
 
-  test('respects coldPool boundary — outside-cold-pool when crossing out', () => {
+  it('respects coldPool boundary — outside-cold-pool when crossing out', () => {
     const isolated = mkdtempSync(join(tmpdir(), 'git-root-isolated-'))
     const inner = join(isolated, 'inner')
     const coldPool = join(isolated, 'pool')
@@ -53,7 +53,7 @@ describe('detectGitRoot', () => {
     expect(r.reason).toBe('outside-cold-pool')
   })
 
-  test('coldPool given, walking up within cold pool finds .git', () => {
+  it('coldPool given, walking up within cold pool finds .git', () => {
     const r = detectGitRoot(subDir, join(root, 'pool'))
     expect(r.gitRoot).toBe(resolve(repoDir))
   })
@@ -70,7 +70,7 @@ describe('gitClone — SOCKS proxy args', () => {
     delete process.env.LYTHOS_SOCKS_PROXY
   })
 
-  test('without LYTHOS_SOCKS_PROXY: no proxy flags in git args', () => {
+  it('without LYTHOS_SOCKS_PROXY: no proxy flags in git args', () => {
     const { mockExec, calls } = createMockExec()
     gitClone('https://github.com/example/repo.git', '/tmp/repo', undefined, mockExec)
     const call = calls.find((c) => c.args.includes('clone'))
@@ -79,7 +79,7 @@ describe('gitClone — SOCKS proxy args', () => {
     expect(call!.args).not.toContain('http.proxy')
   })
 
-  test('with LYTHOS_SOCKS_PROXY: injects -c http.proxy and -c https.proxy', () => {
+  it('with LYTHOS_SOCKS_PROXY: injects -c http.proxy and -c https.proxy', () => {
     process.env.LYTHOS_SOCKS_PROXY = 'proxy.example.com:1080'
     const { mockExec, calls } = createMockExec()
     gitClone('https://github.com/example/repo.git', '/tmp/repo', undefined, mockExec)
@@ -90,7 +90,7 @@ describe('gitClone — SOCKS proxy args', () => {
     expect(call!.args).toContain('https.proxy=socks5://proxy.example.com:1080')
   })
 
-  test('with LYTHOS_SOCKS_PROXY already including socks5://: does not double-prefix', () => {
+  it('with LYTHOS_SOCKS_PROXY already including socks5://: does not double-prefix', () => {
     process.env.LYTHOS_SOCKS_PROXY = 'socks5://proxy.example.com:1080'
     const { mockExec, calls } = createMockExec()
     gitClone('https://github.com/example/repo.git', '/tmp/repo', undefined, mockExec)
@@ -99,7 +99,7 @@ describe('gitClone — SOCKS proxy args', () => {
     expect(call!.args).not.toContain('http.proxy=socks5://socks5://proxy.example.com:1080')
   })
 
-  test('ref checkout also receives proxy flags', () => {
+  it('ref checkout also receives proxy flags', () => {
     process.env.LYTHOS_SOCKS_PROXY = 'proxy.example.com:1080'
     const { mockExec, calls } = createMockExec()
     gitClone('https://github.com/example/repo.git', '/tmp/repo', { ref: 'v1.0.0' }, mockExec)
@@ -118,7 +118,7 @@ describe('gitPull — SOCKS proxy args', () => {
     delete process.env.LYTHOS_SOCKS_PROXY
   })
 
-  test('with LYTHOS_SOCKS_PROXY: injects proxy flags', () => {
+  it('with LYTHOS_SOCKS_PROXY: injects proxy flags', () => {
     process.env.LYTHOS_SOCKS_PROXY = 'proxy.example.com:1080'
     const { mockExec, calls } = createMockExec()
     gitPull('/tmp/repo', 30000, mockExec)

package/src/github-tree.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, it } from 'bun:test'
 import { fetchRepoTree, type FetchFn, type TreeEntry } from './github-tree'
 
 function mockFetch(impl: (url: string, init?: RequestInit) => {
@@ -18,7 +18,7 @@ function mockFetch(impl: (url: string, init?: RequestInit) => {
 }
 
 describe('fetchRepoTree', () => {
-  test('200 → ok with entries', async () => {
+  it('200 → ok with entries', async () => {
     const entries: TreeEntry[] = [
       { path: 'README.md', type: 'blob', sha: 'a' },
       { path: 'skills/pdf/SKILL.md', type: 'blob', sha: 'b' },
@@ -34,7 +34,7 @@ describe('fetchRepoTree', () => {
     expect(res.truncated).toBe(false)
   })
 
-  test('200 with truncated', async () => {
+  it('200 with truncated', async () => {
     const fetch = mockFetch(() => ({
       status: 200,
       body: { tree: [], truncated: true },
@@ -43,14 +43,14 @@ describe('fetchRepoTree', () => {
     expect(res.truncated).toBe(true)
   })
 
-  test('404 → not-found', async () => {
+  it('404 → not-found', async () => {
     const fetch = mockFetch(() => ({ status: 404 }))
     const res = await fetchRepoTree('github.com', 'nope', 'nope', 'HEAD', fetch)
     expect(res.status).toBe('not-found')
     expect(res.httpStatus).toBe(404)
   })
 
-  test('403 with X-RateLimit-Remaining: 0 → rate-limited', async () => {
+  it('403 with X-RateLimit-Remaining: 0 → rate-limited', async () => {
     const fetch = mockFetch(() => ({
       status: 403,
       headers: { 'X-RateLimit-Remaining': '0' },
@@ -59,26 +59,26 @@ describe('fetchRepoTree', () => {
     expect(res.status).toBe('rate-limited')
   })
 
-  test('403 without rate-limit headers → private', async () => {
+  it('403 without rate-limit headers → private', async () => {
     const fetch = mockFetch(() => ({ status: 403 }))
     const res = await fetchRepoTree('github.com', 'o', 'r', 'HEAD', fetch)
     expect(res.status).toBe('private')
   })
 
-  test('network error → network-error', async () => {
+  it('network error → network-error', async () => {
     const fetch = mockFetch(() => ({ status: 0, error: new Error('ENOTFOUND') }))
     const res = await fetchRepoTree('github.com', 'o', 'r', 'HEAD', fetch)
     expect(res.status).toBe('network-error')
     expect(res.message).toContain('ENOTFOUND')
   })
 
-  test('non-github host → unsupported-host', async () => {
+  it('non-github host → unsupported-host', async () => {
     const fetch = mockFetch(() => ({ status: 200 })) // would be ok if fetched
     const res = await fetchRepoTree('gitlab.com', 'o', 'r', 'HEAD', fetch)
     expect(res.status).toBe('unsupported-host')
   })
 
-  test('default ref is HEAD', async () => {
+  it('default ref is HEAD', async () => {
     let capturedUrl = ''
     const fetch = mockFetch((url) => {
       capturedUrl = url
@@ -88,7 +88,7 @@ describe('fetchRepoTree', () => {
     expect(capturedUrl).toContain('/trees/HEAD?recursive=1')
   })
 
-  test('explicit ref is honored', async () => {
+  it('explicit ref is honored', async () => {
     let capturedUrl = ''
     const fetch = mockFetch((url) => {
       capturedUrl = url

package/src/index.ts

@@ -17,6 +17,7 @@ export type {
 
 export { getMirror, rewriteUrl, mirrorUrls } from './mirror.js'
 export { parseLocator, formatLocator } from './parse-locator.js'
+export type { Locator } from './types.js'
 export type { DirEntry, ListPlan, ListPlanEntry } from './cold-pool.js'
 export { ColdPool, DEFAULT_COLD_POOL_PATH, buildListPlan } from './cold-pool.js'
 
@@ -37,6 +38,7 @@ export type { GitCloneOptions, GitPullResult, GitRootResult } from './git-io.js'
 export { gitClone, gitPull, detectGitRoot } from './git-io.js'
 
 export { buildFetchPlan, executeFetchPlan } from './fetch-plan.js'
+export type { FetchIO, FetchPlan, FetchResult } from './types.js'
 
 export { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd } from './git-hash.js'
 

package/src/infer-skill-path.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, it } from 'bun:test'
 import { inferSkillPath } from './infer-skill-path'
 import type { TreeEntry } from './github-tree'
 
@@ -6,13 +6,13 @@ const blob = (path: string): TreeEntry => ({ path, type: 'blob', sha: 'x' })
 const tree = (path: string): TreeEntry => ({ path, type: 'tree', sha: 'x' })
 
 describe('inferSkillPath', () => {
-  test('repo-root SKILL.md → "" candidate', () => {
+  it('repo-root SKILL.md → "" candidate', () => {
     const r = inferSkillPath([blob('SKILL.md'), blob('README.md')])
     expect(r.candidates).toEqual([''])
     expect(r.exactMatch).toBeNull()
   })
 
-  test('monorepo with multiple skills', () => {
+  it('monorepo with multiple skills', () => {
     const r = inferSkillPath([
       blob('skills/pdf/SKILL.md'),
       blob('skills/pdf/script.py'),
@@ -22,7 +22,7 @@ describe('inferSkillPath', () => {
     expect(r.candidates.sort()).toEqual(['skills/excel', 'skills/pdf'])
   })
 
-  test('flat repo (root-level skill dirs)', () => {
+  it('flat repo (root-level skill dirs)', () => {
     const r = inferSkillPath([
       blob('skill-creator/SKILL.md'),
       blob('competitors-analysis/SKILL.md'),
@@ -31,7 +31,7 @@ describe('inferSkillPath', () => {
     expect(r.candidates.sort()).toEqual(['competitors-analysis', 'skill-creator'])
   })
 
-  test('nested monorepo (skills/category/skill)', () => {
+  it('nested monorepo (skills/category/skill)', () => {
     const r = inferSkillPath([
       blob('skills/engineering/tdd/SKILL.md'),
       blob('skills/engineering/diagnose/SKILL.md'),
@@ -39,7 +39,7 @@ describe('inferSkillPath', () => {
     expect(r.candidates.sort()).toEqual(['skills/engineering/diagnose', 'skills/engineering/tdd'])
   })
 
-  test('exactMatch reflects expectedSubpath when present', () => {
+  it('exactMatch reflects expectedSubpath when present', () => {
     const r = inferSkillPath(
       [blob('skills/pdf/SKILL.md'), blob('skills/excel/SKILL.md')],
       'skills/pdf',
@@ -47,7 +47,7 @@ describe('inferSkillPath', () => {
     expect(r.exactMatch).toBe('skills/pdf')
   })
 
-  test('exactMatch is null when expectedSubpath is wrong', () => {
+  it('exactMatch is null when expectedSubpath is wrong', () => {
     const r = inferSkillPath(
       [blob('skills/pdf/SKILL.md')],
       'pdf', // missing the skills/ prefix
@@ -56,7 +56,7 @@ describe('inferSkillPath', () => {
     expect(r.candidates).toEqual(['skills/pdf'])
   })
 
-  test('tree-type entries are ignored (only blobs counted)', () => {
+  it('tree-type entries are ignored (only blobs counted)', () => {
     const r = inferSkillPath([
       tree('SKILL.md'),       // not a real file (tree, not blob)
       blob('skills/x/SKILL.md'),
@@ -64,7 +64,7 @@ describe('inferSkillPath', () => {
     expect(r.candidates).toEqual(['skills/x'])
   })
 
-  test('empty entries → empty candidates', () => {
+  it('empty entries → empty candidates', () => {
     const r = inferSkillPath([])
     expect(r.candidates).toEqual([])
     expect(r.exactMatch).toBeNull()

package/src/mirror.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
 import { probeConnectivity } from './mirror.js'
 
 describe('probeConnectivity', () => {
@@ -51,7 +51,7 @@ describe('probeConnectivity', () => {
   }
 
   // ── Tracer Bullet ──
-  test('direct reachable → returns direct path', async () => {
+  it('direct reachable → returns direct path', async () => {
     mockFetch(
       new Map([
         ['https://example.com/skill', new Response(null, { status: 200 })],
@@ -68,7 +68,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 2 ──
-  test('direct fails, user mirror ok → returns mirror path', async () => {
+  it('direct fails, user mirror ok → returns mirror path', async () => {
     process.env.LYTHOS_GH_MIRROR = 'https://my-mirror.example.com'
     mockFetch(
       new Map([
@@ -87,7 +87,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 3 ──
-  test('all paths fail → returns undefined', async () => {
+  it('all paths fail → returns undefined', async () => {
     mockFetch(new Map())
 
     const result = await probeConnectivity('https://example.com/skill')
@@ -96,7 +96,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 4 ──
-  test('404 is treated as reachable (server alive)', async () => {
+  it('404 is treated as reachable (server alive)', async () => {
     mockFetch(
       new Map([
         ['https://example.com/skill', new Response(null, { status: 404 })],
@@ -109,7 +109,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 5: Racing behavior ──
-  test('probes race concurrently, not sequentially', async () => {
+  it('probes race concurrently, not sequentially', async () => {
     process.env.LYTHOS_GH_MIRROR = 'https://my-mirror.example.com'
     const start = performance.now()
 
@@ -131,7 +131,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 6: No user mirror set → only probes direct ──
-  test('without user mirror, only probes direct', async () => {
+  it('without user mirror, only probes direct', async () => {
     mockFetch(
       new Map([
         ['https://example.com/skill', new Response(null, { status: 200 })],
@@ -146,7 +146,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 7: Timeout honored ──
-  test('timeout aborts slow probes', async () => {
+  it('timeout aborts slow probes', async () => {
     globalThis.fetch = async (_input, init?) => {
       return new Promise((_, reject) => {
         const timer = setTimeout(
@@ -169,7 +169,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 8: SOCKS proxy routing ──
-  test('SOCKS proxy set, curl succeeds → returns direct path', async () => {
+  it('SOCKS proxy set, curl succeeds → returns direct path', async () => {
     process.env.LYTHOS_SOCKS_PROXY = '127.0.0.1:1080'
     const execCalls: Array<{ file: string; args: string[] }> = []
 
@@ -193,7 +193,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 9: SOCKS proxy with socks5:// prefix ──
-  test('SOCKS proxy already has socks5:// prefix → does not double-prefix', async () => {
+  it('SOCKS proxy already has socks5:// prefix → does not double-prefix', async () => {
     process.env.LYTHOS_SOCKS_PROXY = 'socks5://proxy.example.com:1080'
     const execCalls: Array<{ file: string; args: string[] }> = []
 
@@ -210,7 +210,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 10: SOCKS proxy fails → no automatic unproxied fallback ──
-  test('SOCKS proxy fails → no automatic unproxied fallback', async () => {
+  it('SOCKS proxy fails → no automatic unproxied fallback', async () => {
     process.env.LYTHOS_SOCKS_PROXY = '127.0.0.1:1080'
 
     const result = await probeConnectivity('https://example.com/skill', 3000, {
@@ -228,7 +228,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Vertical Slice 11: SOCKS proxy only affects direct, mirror still works ──
-  test('SOCKS proxy fails but mirror succeeds', async () => {
+  it('SOCKS proxy fails but mirror succeeds', async () => {
     process.env.LYTHOS_SOCKS_PROXY = '127.0.0.1:1080'
     process.env.LYTHOS_GH_MIRROR = 'https://my-mirror.example.com'
     const execCalls: Array<{ file: string; args: string[] }> = []
@@ -253,7 +253,7 @@ describe('probeConnectivity', () => {
   })
 
   // ── Backward compat: legacy env var name still works ──
-  test('LYTHOSKILL_GH_MIRROR (legacy) still works with deprecation warning', async () => {
+  it('LYTHOSKILL_GH_MIRROR (legacy) still works with deprecation warning', async () => {
     // Ensure new name is not set
     delete process.env.LYTHOS_GH_MIRROR
     process.env.LYTHOSKILL_GH_MIRROR = 'https://legacy-mirror.example.com'

package/src/parse-locator.test.ts

@@ -1,8 +1,8 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, it } from 'bun:test'
 import { formatLocator, parseLocator } from './parse-locator'
 
 describe('parseLocator — accepted forms', () => {
-  test('host.tld/owner/repo/skill (monorepo)', () => {
+  it('host.tld/owner/repo/skill (monorepo)', () => {
     const loc = parseLocator('github.com/anthropics/skills/skills/pdf')
     expect(loc).toEqual({
       raw: 'github.com/anthropics/skills/skills/pdf',
@@ -15,19 +15,19 @@ describe('parseLocator — accepted forms', () => {
     })
   })
 
-  test('host.tld/owner/repo/skill (nested skill subpath)', () => {
+  it('host.tld/owner/repo/skill (nested skill subpath)', () => {
     const loc = parseLocator('github.com/mattpocock/skills/skills/engineering/tdd')
     expect(loc?.skill).toBe('skills/engineering/tdd')
     expect(loc?.repo).toBe('skills')
   })
 
-  test('host.tld/owner/repo/skill (flat repo, single skill segment)', () => {
+  it('host.tld/owner/repo/skill (flat repo, single skill segment)', () => {
     const loc = parseLocator('github.com/daymade/claude-code-skills/skill-creator')
     expect(loc?.skill).toBe('skill-creator')
     expect(loc?.repo).toBe('claude-code-skills')
   })
 
-  test('host.tld/owner/repo (standalone — skill = null)', () => {
+  it('host.tld/owner/repo (standalone — skill = null)', () => {
     const loc = parseLocator('github.com/SpillwaveSolutions/design-doc-mermaid')
     expect(loc).toEqual({
       raw: 'github.com/SpillwaveSolutions/design-doc-mermaid',
@@ -40,12 +40,12 @@ describe('parseLocator — accepted forms', () => {
     })
   })
 
-  test('host.tld/owner/repo/skill (arbitrary subdir name)', () => {
+  it('host.tld/owner/repo/skill (arbitrary subdir name)', () => {
     const loc = parseLocator('github.com/Cocoon-AI/architecture-diagram-generator/architecture-diagram')
     expect(loc?.skill).toBe('architecture-diagram')
   })
 
-  test('localhost/<owner>/<repo> (canonical local skill, same shape as remote)', () => {
+  it('localhost/<owner>/<repo> (canonical local skill, same shape as remote)', () => {
     const loc = parseLocator('localhost/me/my-skill')
     expect(loc).toEqual({
       raw: 'localhost/me/my-skill',
@@ -58,42 +58,42 @@ describe('parseLocator — accepted forms', () => {
     })
   })
 
-  test('non-github host accepted', () => {
+  it('non-github host accepted', () => {
     const loc = parseLocator('gitlab.com/owner/repo/skill-x')
     expect(loc?.host).toBe('gitlab.com')
     expect(loc?.skill).toBe('skill-x')
   })
 
-  test('input is trimmed', () => {
+  it('input is trimmed', () => {
     const loc = parseLocator('  github.com/owner/repo  ')
     expect(loc?.repo).toBe('repo')
   })
 })
 
 describe('parseLocator — rejected forms (per ADR-20260502012643244 FQ-only)', () => {
-  test('empty string', () => {
+  it('empty string', () => {
     expect(parseLocator('')).toBeNull()
     expect(parseLocator('   ')).toBeNull()
   })
 
-  test('single segment', () => {
+  it('single segment', () => {
     expect(parseLocator('my-skill')).toBeNull()
   })
 
-  test('bare owner/repo (no host) is rejected — must be FQ', () => {
+  it('bare owner/repo (no host) is rejected — must be FQ', () => {
     expect(parseLocator('daymade/claude-code-skills')).toBeNull()
     expect(parseLocator('owner/repo/skill')).toBeNull()
   })
 
-  test('host without dot is treated as bare', () => {
+  it('host without dot is treated as bare', () => {
     expect(parseLocator('foo/bar/baz')).toBeNull()
   })
 
-  test('host.tld/owner without repo segment', () => {
+  it('host.tld/owner without repo segment', () => {
     expect(parseLocator('github.com/owner')).toBeNull()
   })
 
-  test('localhost with multi-segment path (skill subpath beyond owner/repo)', () => {
+  it('localhost with multi-segment path (skill subpath beyond owner/repo)', () => {
     const loc = parseLocator('localhost/me/skills/my-skill')
     expect(loc).toEqual({
       raw: 'localhost/me/skills/my-skill',
@@ -106,17 +106,17 @@ describe('parseLocator — rejected forms (per ADR-20260502012643244 FQ-only)',
     })
   })
 
-  test('localhost alone (no owner/repo) is rejected', () => {
+  it('localhost alone (no owner/repo) is rejected', () => {
     expect(parseLocator('localhost')).toBeNull()
   })
 
-  test('localhost/<name> (2 segments) is rejected — use localhost/me/<skill> for quick local form', () => {
+  it('localhost/<name> (2 segments) is rejected — use localhost/me/<skill> for quick local form', () => {
     expect(parseLocator('localhost/my-skill')).toBeNull()
   })
 })
 
 describe('formatLocator — round-trips', () => {
-  test.each([
+  it.each([
     'github.com/anthropics/skills/skills/pdf',
     'github.com/SpillwaveSolutions/design-doc-mermaid',
     'github.com/mattpocock/skills/skills/engineering/tdd',

package/src/prune-plan.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
 import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -48,20 +48,20 @@ describe('buildPrunePlan — plan-mode (IO via ColdPool + test filesystem)', ()
     rmSync(root, { recursive: true, force: true })
   })
 
-  test('identifies unreferenced repos as prune candidates', () => {
+  it('identifies unreferenced repos as prune candidates', () => {
     const plan = buildPrunePlan(root)
     expect(plan.candidates.length).toBe(1)
     expect(plan.candidates[0].repoRel).toBe('github.com/org/repo-b')
   })
 
-  test('does NOT flag actively referenced repos', () => {
+  it('does NOT flag actively referenced repos', () => {
     const plan = buildPrunePlan(root)
     const rels = plan.candidates.map(c => c.repoRel)
     expect(rels).not.toContain('github.com/org/repo-a')
     expect(rels).not.toContain('github.com/org/repo-c')
   })
 
-  test('empty cold pool → empty plan', () => {
+  it('empty cold pool → empty plan', () => {
     const emptyDir = mkdtempSync(join(tmpdir(), 'prune-empty-'))
     const plan = buildPrunePlan(emptyDir)
     expect(plan.candidates).toEqual([])
@@ -69,7 +69,7 @@ describe('buildPrunePlan — plan-mode (IO via ColdPool + test filesystem)', ()
     rmSync(emptyDir, { recursive: true, force: true })
   })
 
-  test('plan includes coldPoolPath and totalSize', () => {
+  it('plan includes coldPoolPath and totalSize', () => {
     const plan = buildPrunePlan(root)
     expect(plan.coldPoolPath).toBe(root)
     expect(plan.totalSize).toBeGreaterThan(0)
@@ -77,7 +77,7 @@ describe('buildPrunePlan — plan-mode (IO via ColdPool + test filesystem)', ()
 })
 
 describe('executePrunePlan — plan-mode (IO injected)', () => {
-  test('calls delete for each candidate', () => {
+  it('calls delete for each candidate', () => {
     const deleted: string[] = []
     const plan = {
       coldPoolPath: '/pool',
@@ -97,7 +97,7 @@ describe('executePrunePlan — plan-mode (IO injected)', () => {
     expect(results[1].deleted).toBe(true)
   })
 
-  test('logs count and total size', () => {
+  it('logs count and total size', () => {
     const logs: string[] = []
     executePrunePlan({
       coldPoolPath: '/pool',
@@ -112,7 +112,7 @@ describe('executePrunePlan — plan-mode (IO injected)', () => {
     expect(joined).toContain('500')
   })
 
-  test('skips delete when candidates array empty', () => {
+  it('skips delete when candidates array empty', () => {
     let called = false
     const results = executePrunePlan(
       { coldPoolPath: '/pool', candidates: [], totalSize: 0 },

package/src/reconcile-plan.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, beforeEach, afterEach } from 'bun:test'
+import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
 import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -34,7 +34,7 @@ describe('buildReconcilePlan — pure classification', () => {
     rmSync(root, { recursive: true, force: true })
   })
 
-  test('empty desired + empty cold pool → all empty', () => {
+  it('empty desired + empty cold pool → all empty', () => {
     const desired: ReconcileDesiredState = { deckPath: '/project/skill-deck.toml', skills: [] }
     const plan = buildReconcilePlan(pool, desired)
     expect(plan.missing).toEqual([])
@@ -42,7 +42,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.extra).toEqual([])
   })
 
-  test('desired skill missing from cold pool → reported as missing', () => {
+  it('desired skill missing from cold pool → reported as missing', () => {
     const desired: ReconcileDesiredState = {
       deckPath: '/project/skill-deck.toml',
       skills: [{ locator: 'github.com/lythos-labs/tdd', alias: 'tdd' }],
@@ -57,7 +57,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.extra).toEqual([])
   })
 
-  test('desired skill exists in cold pool with metadata → reported as behind', () => {
+  it('desired skill exists in cold pool with metadata → reported as behind', () => {
     seedRepo(root, 'github.com', 'owner', 'repo-a')
     pool.metadata.recordRepoRef('github.com', 'owner', 'repo-a', 'abc123def')
 
@@ -73,7 +73,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.extra).toEqual([])
   })
 
-  test('desired skill exists but no metadata → not flagged (manual clone)', () => {
+  it('desired skill exists but no metadata → not flagged (manual clone)', () => {
     seedRepo(root, 'github.com', 'owner', 'repo-b')
 
     const desired: ReconcileDesiredState = {
@@ -86,7 +86,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.extra).toEqual([])
   })
 
-  test('monorepo skill path → extracts correct repo root', () => {
+  it('monorepo skill path → extracts correct repo root', () => {
     seedRepo(root, 'github.com', 'owner', 'monorepo')
     pool.metadata.recordRepoRef('github.com', 'owner', 'monorepo', 'def456')
 
@@ -100,7 +100,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.behind[0].repo).toBe('monorepo')
   })
 
-  test('extra repo in cold pool not in desired → reported as extra', () => {
+  it('extra repo in cold pool not in desired → reported as extra', () => {
     seedRepo(root, 'github.com', 'someone', 'orphan-repo')
 
     const desired: ReconcileDesiredState = {
@@ -113,7 +113,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.extra[0].repo).toBe('orphan-repo')
   })
 
-  test('multiple skills in same repo → single repo entry', () => {
+  it('multiple skills in same repo → single repo entry', () => {
     seedRepo(root, 'github.com', 'owner', 'shared-repo')
     pool.metadata.recordRepoRef('github.com', 'owner', 'shared-repo', 'ghi789')
 
@@ -130,7 +130,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.behind[0].aliases).toEqual(['alpha', 'beta'])
   })
 
-  test('localhost skill in desired, exists in pool', () => {
+  it('localhost skill in desired, exists in pool', () => {
     seedRepo(root, 'localhost', 'me', 'local-skill')
 
     const desired: ReconcileDesiredState = {
@@ -144,7 +144,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.extra).toEqual([])
   })
 
-  test('unrecognized locator format → reported as missing', () => {
+  it('unrecognized locator format → reported as missing', () => {
     const desired: ReconcileDesiredState = {
       deckPath: '/project/skill-deck.toml',
       skills: [{ locator: 'bare-name', alias: 'bare' }],
@@ -154,7 +154,7 @@ describe('buildReconcilePlan — pure classification', () => {
     expect(plan.missing[0].reason).toContain('Unrecognized')
   })
 
-  test('mixed: missing + behind + extra all populated', () => {
+  it('mixed: missing + behind + extra all populated', () => {
     // Seed two repos that exist
     seedRepo(root, 'github.com', 'owner', 'exists-behind')
     pool.metadata.recordRepoRef('github.com', 'owner', 'exists-behind', 'abc')
@@ -185,12 +185,12 @@ describe('buildReconcilePlan — pure classification', () => {
 })
 
 describe('executeReconcilePlan — plan-first reporting', () => {
-  test('empty plan → all zero count', () => {
+  it('empty plan → all zero count', () => {
     const results = executeReconcilePlan({ missing: [], behind: [], extra: [] })
     expect(results).toEqual([])
   })
 
-  test('missing entry → failed status', () => {
+  it('missing entry → failed status', () => {
     const plan = {
       missing: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/pool/github.com/o/r', reason: 'Not found', aliases: ['r'] }],
       behind: [],
@@ -201,7 +201,7 @@ describe('executeReconcilePlan — plan-first reporting', () => {
     expect(results[0].status).toBe('failed')
   })
 
-  test('behind entry → skipped status', () => {
+  it('behind entry → skipped status', () => {
     const plan = {
       missing: [],
       behind: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/pool/github.com/o/r', reason: 'HEAD mismatch', aliases: ['r'] }],
@@ -211,7 +211,7 @@ describe('executeReconcilePlan — plan-first reporting', () => {
     expect(results[0].status).toBe('skipped')
   })
 
-  test('extra entry → extra-reported status', () => {
+  it('extra entry → extra-reported status', () => {
     const plan = {
       missing: [],
       behind: [],
@@ -221,7 +221,7 @@ describe('executeReconcilePlan — plan-first reporting', () => {
     expect(results[0].status).toBe('extra-reported')
   })
 
-  test('io.log captures output', () => {
+  it('io.log captures output', () => {
     const lines: string[] = []
     const plan = {
       missing: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/p/github.com/o/r', reason: 'X', aliases: ['r'] }],

package/src/validate-plan.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, it } from 'bun:test'
 import { buildValidationPlan, executeValidationPlan, type ValidationCheck, type ValidationIO } from './validate-plan'
 import type { FetchFn, TreeEntry } from './github-tree'
 
@@ -18,25 +18,25 @@ const treeFor = (paths: string[]): TreeEntry[] =>
 const ioWith = (fetch: FetchFn): ValidationIO => ({ fetch })
 
 describe('buildValidationPlan', () => {
-  test('parses input and stores defaults', () => {
+  it('parses input and stores defaults', () => {
     const plan = buildValidationPlan('github.com/owner/repo')
     expect(plan.locator?.repo).toBe('repo')
     expect(plan.checks).toEqual(['syntax', 'remote', 'path'])
   })
 
-  test('parse failure → locator null', () => {
+  it('parse failure → locator null', () => {
     const plan = buildValidationPlan('bad-name')
     expect(plan.locator).toBeNull()
   })
 
-  test('honors custom checks', () => {
+  it('honors custom checks', () => {
     const plan = buildValidationPlan('localhost/me/x', { checks: ['syntax'] })
     expect(plan.checks).toEqual(['syntax'])
   })
 })
 
 describe('executeValidationPlan — syntax phase', () => {
-  test('parse failure → invalid + suggested fix', async () => {
+  it('parse failure → invalid + suggested fix', async () => {
     const plan = buildValidationPlan('bad-name')
     const report = await executeValidationPlan(plan)
     expect(report.status).toBe('invalid')
@@ -45,7 +45,7 @@ describe('executeValidationPlan — syntax phase', () => {
     expect(report.suggestedFixes.length).toBe(1)
   })
 
-  test('localhost short-circuits — no remote fetch', async () => {
+  it('localhost short-circuits — no remote fetch', async () => {
     const plan = buildValidationPlan('localhost/me/my-skill')
     let fetched = false
     const io = ioWith(async () => {
@@ -59,7 +59,7 @@ describe('executeValidationPlan — syntax phase', () => {
 })
 
 describe('executeValidationPlan — remote phase', () => {
-  test('404 → invalid (repo-existence)', async () => {
+  it('404 → invalid (repo-existence)', async () => {
     const plan = buildValidationPlan('github.com/nope/nope')
     const report = await executeValidationPlan(plan, ioWith(mockFetch(() => ({ status: 404 }))))
     expect(report.status).toBe('invalid')
@@ -67,7 +67,7 @@ describe('executeValidationPlan — remote phase', () => {
     expect(report.findings.repoExists).toBe(false)
   })
 
-  test('rate-limit → ambiguous', async () => {
+  it('rate-limit → ambiguous', async () => {
     const plan = buildValidationPlan('github.com/owner/repo')
     const report = await executeValidationPlan(
       plan,
@@ -77,7 +77,7 @@ describe('executeValidationPlan — remote phase', () => {
     expect(report.phase).toBe('repo-existence')
   })
 
-  test('private repo → ambiguous with hint', async () => {
+  it('private repo → ambiguous with hint', async () => {
     const plan = buildValidationPlan('github.com/owner/repo')
     const report = await executeValidationPlan(plan, ioWith(mockFetch(() => ({ status: 403 }))))
     expect(report.status).toBe('ambiguous')
@@ -86,7 +86,7 @@ describe('executeValidationPlan — remote phase', () => {
 })
 
 describe('executeValidationPlan — path phase', () => {
-  test('standalone (skill=null) with SKILL.md at root → valid', async () => {
+  it('standalone (skill=null) with SKILL.md at root → valid', async () => {
     const plan = buildValidationPlan('github.com/owner/standalone')
     const fetch = mockFetch(() => ({
       status: 200,
@@ -98,7 +98,7 @@ describe('executeValidationPlan — path phase', () => {
     expect(report.findings.skillMdFound).toBe(true)
   })
 
-  test('standalone but skills exist in subdirs → invalid + qualified-locator suggestions', async () => {
+  it('standalone but skills exist in subdirs → invalid + qualified-locator suggestions', async () => {
     const plan = buildValidationPlan('github.com/owner/repo')
     const fetch = mockFetch(() => ({
       status: 200,
@@ -113,7 +113,7 @@ describe('executeValidationPlan — path phase', () => {
     ])
   })
 
-  test('skill subpath matches → valid', async () => {
+  it('skill subpath matches → valid', async () => {
     const plan = buildValidationPlan('github.com/anthropics/skills/skills/pdf')
     const fetch = mockFetch(() => ({
       status: 200,
@@ -123,7 +123,7 @@ describe('executeValidationPlan — path phase', () => {
     expect(report.status).toBe('valid')
   })
 
-  test('skill subpath wrong → invalid + corrected suggestion', async () => {
+  it('skill subpath wrong → invalid + corrected suggestion', async () => {
     const plan = buildValidationPlan('github.com/anthropics/skills/pdf')  // missing skills/ prefix
     const fetch = mockFetch(() => ({
       status: 200,
@@ -135,7 +135,7 @@ describe('executeValidationPlan — path phase', () => {
     expect(report.suggestedFixes.some((f) => f.newLocator === 'github.com/anthropics/skills/skills/pdf')).toBe(true)
   })
 
-  test('repo with no SKILL.md anywhere → invalid + web-search hint', async () => {
+  it('repo with no SKILL.md anywhere → invalid + web-search hint', async () => {
     const plan = buildValidationPlan('github.com/owner/random-repo')
     const fetch = mockFetch(() => ({
       status: 200,
@@ -148,7 +148,7 @@ describe('executeValidationPlan — path phase', () => {
 })
 
 describe('executeValidationPlan — scoped checks', () => {
-  test('checks: ["syntax"] — no remote fetch even for non-localhost', async () => {
+  it('checks: ["syntax"] — no remote fetch even for non-localhost', async () => {
     const plan = buildValidationPlan('github.com/o/r', { checks: ['syntax'] })
     let fetched = false
     const io = ioWith(async () => {