@lythos/skill-deck 0.9.1 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/link.ts

@@ -79,6 +79,15 @@ export function findSource(name: string, coldPool: string, projectDir: string):
     if (existsSync(join(directPath, "SKILL.md"))) return { path: directPath };
   }
 
+  // 0.5 localhost skills: localhost/skill → cold_pool/skill
+  if (name.startsWith('localhost/')) {
+    const skill = name.slice('localhost/'.length);
+    if (skill) {
+      const localPath = join(coldPool, skill);
+      if (existsSync(join(localPath, "SKILL.md"))) return { path: localPath };
+    }
+  }
+
   // 1. 直接路径
   const direct = resolve(coldPool, name);
   if (existsSync(join(direct, "SKILL.md"))) return { path: direct };

package/src/prune-plan.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect } from 'bun:test'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolvePruneConfig, scanColdPool, calculateDirSize, buildPrunePlan } from './prune-plan'
+
+const deckToml = `[deck]
+cold_pool = "./cold-pool"
+
+[tool.skills.skill-a]
+path = "github.com/foo/bar/skill-a"
+
+[tool.skills.skill-b]
+path = "localhost/skill-b"
+`
+
+describe('resolvePruneConfig', () => {
+  test('explicit paths override defaults', () => {
+    const cfg = resolvePruneConfig({
+      deckPath: '/tmp/deck.toml',
+      workdir: '/custom/work',
+      coldPool: '/custom/pool',
+    })
+    expect(cfg.deckPath).toBe('/tmp/deck.toml')
+    expect(cfg.workdir).toBe('/custom/work')
+    expect(cfg.coldPool).toBe('/custom/pool')
+  })
+})
+
+describe('scanColdPool', () => {
+  test('empty for nonexistent directory', () => {
+    expect(scanColdPool('/tmp/nonexistent-' + Date.now())).toEqual([])
+  })
+
+  test('finds flat localhost skills in cold pool', () => {
+    const pool = join('/tmp', 'prune-test-pool-' + Date.now())
+    mkdirSync(join(pool, 'skill-b'), { recursive: true })
+    writeFileSync(join(pool, 'skill-b', 'SKILL.md'), '# test')
+
+    const repos = scanColdPool(pool)
+    expect(repos.some(r => r.endsWith('skill-b'))).toBe(true)
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+})
+
+describe('calculateDirSize', () => {
+  test('calculates total size', () => {
+    const dir = join('/tmp', 'size-test-' + Date.now())
+    mkdirSync(join(dir, 'sub'), { recursive: true })
+    writeFileSync(join(dir, 'a.txt'), 'hello')
+    writeFileSync(join(dir, 'sub', 'b.txt'), 'world')
+
+    const size = calculateDirSize(dir)
+    expect(size).toBeGreaterThanOrEqual(10) // 'hello' + 'world' = 10 bytes
+    rmSync(dir, { recursive: true, force: true })
+  })
+})
+
+describe('buildPrunePlan', () => {
+  test('builds plan from deck config', () => {
+    const plan = buildPrunePlan(deckToml, { coldPool: '/tmp/test-pool' })
+    expect(plan.declared).toHaveLength(2)
+    expect(plan.declared).toContain('github.com/foo/bar/skill-a')
+  })
+
+  test('identifies unreferenced repos as candidates', () => {
+    const pool = join('/tmp', 'prune-plan-test-' + Date.now())
+    // Create a declared repo
+    mkdirSync(join(pool, 'github.com', 'foo', 'bar', 'skill-a'), { recursive: true })
+    // Create an UNREFERENCED repo (not in deck)
+    mkdirSync(join(pool, 'github.com', 'baz', 'qux'), { recursive: true })
+
+    const plan = buildPrunePlan(deckToml, { coldPool: pool })
+    const unreferenced = plan.candidates.map(c => c.repoRel)
+    expect(unreferenced).toContain('github.com/baz/qux')
+    // skill-a is declared, should NOT be a candidate
+    expect(unreferenced).not.toContain('github.com/foo/bar/skill-a')
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+
+  test('empty candidates when all repos declared', () => {
+    const pool = join('/tmp', 'prune-all-declared-' + Date.now())
+    mkdirSync(join(pool, 'github.com', 'foo', 'bar', 'skill-a'), { recursive: true })
+    mkdirSync(join(pool, 'localhost', 'skill-b'), { recursive: true })
+
+    const plan = buildPrunePlan(deckToml, { coldPool: pool })
+    expect(plan.candidates).toHaveLength(0)
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+
+  test('totalSize is sum of candidate sizes', () => {
+    const pool = join('/tmp', 'prune-size-test-' + Date.now())
+    mkdirSync(join(pool, 'github.com', 'unref', 'repo'), { recursive: true })
+    writeFileSync(join(pool, 'github.com', 'unref', 'repo', 'data.txt'), 'hello world')
+
+    const plan = buildPrunePlan(deckToml, { coldPool: pool })
+    expect(plan.totalSize).toBeGreaterThanOrEqual(11)
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+})

package/src/prune-plan.ts

@@ -0,0 +1,188 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { findDeckToml, expandHome } from './link'
+import { parseDeck } from './parse-deck'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface PruneCandidate {
+  repoPath: string
+  repoRel: string                  // relative to cold pool
+  size: number                     // bytes
+}
+
+export interface PrunePlan {
+  deckPath: string
+  workdir: string
+  coldPool: string
+  candidates: PruneCandidate[]     // unreferenced repos to delete
+  declared: string[]               // declared skill names (for audit)
+  totalSize: number                // total reclaimable bytes
+}
+
+// ── Config resolution ──────────────────────────────────────────────────────
+
+export function resolvePruneConfig(opts?: {
+  deckPath?: string
+  workdir?: string
+  coldPool?: string
+}) {
+  const deckPath = opts?.deckPath
+    ? resolve(opts.deckPath)
+    : (findDeckToml(process.cwd()) || resolve('skill-deck.toml'))
+
+  const workdir = opts?.workdir
+    ? resolve(opts.workdir)
+    : join(deckPath, '..')
+
+  const coldPool = opts?.coldPool
+    ? resolve(opts.coldPool)
+    : expandHome('~/.agents/skill-repos', workdir)
+
+  return { deckPath, workdir, coldPool }
+}
+
+// ── Cold pool scanner (pure: reads, no delete) ─────────────────────────────
+
+export function scanColdPool(coldPool: string): string[] {
+  const repos: string[] = []
+  if (!existsSync(coldPool)) return repos
+
+  try {
+    for (const host of readdirSync(coldPool, { withFileTypes: true })) {
+      if (!host.isDirectory() || host.name.startsWith('.')) continue
+      const hostPath = join(coldPool, host.name)
+
+      // Flat skill: cold-pool/skill-name/SKILL.md (localhost style)
+      if (existsSync(join(hostPath, 'SKILL.md'))) {
+        repos.push(hostPath)
+        continue
+      }
+
+      // Nested: cold-pool/github.com/owner/repo/
+      for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
+        if (!owner.isDirectory() || owner.name.startsWith('.')) continue
+        const ownerPath = join(hostPath, owner.name)
+        for (const repo of readdirSync(ownerPath, { withFileTypes: true })) {
+          if (!repo.isDirectory() || repo.name.startsWith('.')) continue
+          repos.push(join(ownerPath, repo.name))
+        }
+      }
+    }
+  } catch {}
+
+  return repos
+}
+
+// ── Size calculation (pure helper) ─────────────────────────────────────────
+
+export function calculateDirSize(dir: string): number {
+  let total = 0
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        total += calculateDirSize(p)
+      } else if (entry.isFile()) {
+        total += statSync(p).size
+      }
+    }
+  } catch {}
+  return total
+}
+
+// ── Plan builder (pure: no deletion, no mutation) ──────────────────────────
+
+export function buildPrunePlan(
+  deckRaw: string,
+  opts?: { deckPath?: string; workdir?: string; coldPool?: string }
+): PrunePlan {
+  const { deckPath, workdir, coldPool: configuredColdPool } = resolvePruneConfig(opts)
+
+  // Read cold_pool from deck.toml if not explicitly overridden
+  let coldPool = configuredColdPool
+  if (!opts?.coldPool) {
+    const deckMatch = deckRaw.match(/cold_pool\s*=\s*"([^"]+)"/)
+    if (deckMatch) {
+      coldPool = expandHome(deckMatch[1], workdir)
+    }
+  }
+
+  // Get declared skill paths from deck
+  const { entries: declared } = parseDeck(deckRaw)
+  const declaredPaths = new Set(declared.map(d => d.path))
+
+  // Scan cold pool for all repos
+  const allRepos = scanColdPool(coldPool)
+
+  // Find unreferenced: repos not declared in deck
+  const candidates: PruneCandidate[] = []
+  for (const repoPath of allRepos) {
+    // A repo is referenced if any declared skill path starts with its cold-pool-relative path
+    const repoRel = repoPath.slice(coldPool.length + 1) // relative to cold pool
+    const isReferenced = [...declaredPaths].some(d => d.startsWith(repoRel) || repoRel.startsWith(d))
+
+    if (!isReferenced) {
+      candidates.push({
+        repoPath,
+        repoRel,
+        size: calculateDirSize(repoPath),
+      })
+    }
+  }
+
+  const totalSize = candidates.reduce((sum, c) => sum + c.size, 0)
+
+  return {
+    deckPath,
+    workdir,
+    coldPool,
+    candidates,
+    declared: declared.map(d => d.path),
+    totalSize,
+  }
+}
+
+// ── Execution (IO layer, injectable for testing) ───────────────────────────
+
+export interface PruneResult {
+  repoRel: string
+  deleted: boolean
+  error?: string
+}
+
+export interface PruneIO {
+  delete?: (path: string) => void
+  log?: (msg: string) => void
+  formatSize?: (bytes: number) => string
+}
+
+export function executePrunePlan(plan: PrunePlan, io?: PruneIO): PruneResult[] {
+  const deleteFn = io?.delete ?? ((_path: string) => { throw new Error('delete not injected') })
+  const log = io?.log ?? (() => {})
+  const fmtSize = io?.formatSize ?? ((b: number) => b < 1024 ? `${b}B` : b < 1024 * 1024 ? `${(b / 1024).toFixed(1)}KB` : `${(b / (1024 * 1024)).toFixed(1)}MB`)
+
+  log(`\n🧹 Prune candidates — ${plan.candidates.length} repo(s), ${fmtSize(plan.totalSize)} total:\n`)
+  for (const c of plan.candidates) {
+    log(`   ${c.repoRel} (${fmtSize(c.size)})`)
+  }
+
+  const results: PruneResult[] = []
+  let deleted = 0, failed = 0
+
+  for (const c of plan.candidates) {
+    try {
+      deleteFn(c.repoPath)
+      log(`  🗑️  Deleted: ${c.repoRel}`)
+      results.push({ repoRel: c.repoRel, deleted: true })
+      deleted++
+    } catch (err: any) {
+      log(`  ❌ Failed to delete ${c.repoRel}: ${err.message}`)
+      results.push({ repoRel: c.repoRel, deleted: false, error: err.message })
+      failed++
+    }
+  }
+
+  log(`\n📦 Prune complete: ${deleted} deleted, ${failed} failed`)
+  return results
+}

package/src/prune.ts

@@ -7,12 +7,11 @@
  * Does NOT modify deck.toml or the working set.
  */
 
-import { parse as parseToml } from "@iarna/toml";
-import { existsSync, readFileSync, readdirSync, statSync, rmSync } from "node:fs";
-import { resolve, dirname, join, relative } from "node:path";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { findDeckToml, expandHome, findSource } from "./link.js";
-import { parseDeck } from "./parse-deck.js";
+import { findDeckToml } from "./link.js";
+import { buildPrunePlan, executePrunePlan } from "./prune-plan.js";
 
 interface PruneCandidate {
   repoPath: string;
@@ -48,9 +47,23 @@ function scanColdPoolRepos(coldPool: string): string[] {
     for (const host of readdirSync(coldPool, { withFileTypes: true })) {
       if (!host.isDirectory() || host.name.startsWith(".")) continue;
       const hostPath = join(coldPool, host.name);
+
+      // Flat skill: cold-pool/skill-name/ (localhost style)
+      if (existsSync(join(hostPath, "SKILL.md"))) {
+        repos.push(hostPath);
+        continue;
+      }
+
       for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
         if (!owner.isDirectory() || owner.name.startsWith(".")) continue;
         const ownerPath = join(hostPath, owner.name);
+
+        // Standalone repo: cold-pool/host.tld/owner/repo/
+        if (existsSync(join(ownerPath, "SKILL.md"))) {
+          repos.push(ownerPath);
+          continue;
+        }
+
         for (const repo of readdirSync(ownerPath, { withFileTypes: true })) {
           if (!repo.isDirectory() || repo.name.startsWith(".")) continue;
           repos.push(join(ownerPath, repo.name));
@@ -89,108 +102,60 @@ async function confirm(message: string): Promise<boolean> {
 }
 
 export async function pruneDeck(cliDeckPath?: string, cliWorkdir?: string, yes?: boolean): Promise<void> {
-  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
-  const DECK_PATH = cliDeck
-    ? resolve(cliDeck)
-    : findDeckToml(process.cwd()) || resolve("skill-deck.toml");
-
-  if (!existsSync(DECK_PATH)) {
-    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`);
-    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
-    process.exit(1);
-  }
-
-  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
-  const deckRaw = readFileSync(DECK_PATH, "utf-8");
-  const deck = parseToml(deckRaw) as any;
-
-  const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
-
-  // ── 收集声明 ────────────────────────────────────────────────
-
-  const { entries: parsedEntries } = parseDeck(deckRaw);
-  const declaredPaths = parsedEntries.map(e => e.path);
+  const deckPath = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
+  const workdir = cliWorkdir
 
-  // Legacy string-array fallback
-  for (const section of ["innate", "tool", "combo"] as const) {
-    const skills = deck[section]?.skills;
-    if (Array.isArray(skills)) {
-      for (const name of skills) {
-        if (name && typeof name === "string" && !declaredPaths.includes(name)) {
-          declaredPaths.push(name);
-        }
-      }
-    }
-  }
+  const DECK_PATH = deckPath ? resolve(deckPath) : findDeckToml(process.cwd()) || resolve('skill-deck.toml')
 
-  // ── 扫描 cold pool ──────────────────────────────────────────
-
-  if (!existsSync(COLD_POOL)) {
-    console.log("📭 Cold pool does not exist. Nothing to prune.");
-    process.exit(0);
+  if (!existsSync(DECK_PATH)) {
+    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`)
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`)
+    process.exit(1)
   }
 
-  const allRepos = scanColdPoolRepos(COLD_POOL);
-  if (allRepos.length === 0) {
-    console.log("📭 Cold pool is empty. Nothing to prune.");
-    process.exit(0);
-  }
+  const deckRaw = readFileSync(DECK_PATH, 'utf-8')
 
-  // ── 求差集 ──────────────────────────────────────────────────
+  // ── Plan: pure unreferenced detection ──────────────────────────────
+  const plan = buildPrunePlan(deckRaw, {
+    deckPath: DECK_PATH,
+    workdir: workdir ? resolve(workdir) : undefined,
+  })
 
-  const candidates: PruneCandidate[] = [];
-  for (const repoPath of allRepos) {
-    if (isRepoReferenced(repoPath, declaredPaths, COLD_POOL, PROJECT_DIR)) continue;
-    const size = calculateDirSize(repoPath);
-    candidates.push({ repoPath, repoRel: relative(COLD_POOL, repoPath), size });
+  if (!existsSync(plan.coldPool)) {
+    console.log('📭 Cold pool does not exist. Nothing to prune.')
+    process.exit(0)
   }
 
-  if (candidates.length === 0) {
-    console.log("✅ All cold pool repositories are referenced. Nothing to prune.");
-    process.exit(0);
+  if (plan.candidates.length === 0 && plan.declared.length === 0) {
+    console.log('📭 Cold pool is empty. Nothing to prune.')
+    process.exit(0)
   }
 
-  // ── 报告 ────────────────────────────────────────────────────
-
-  const totalSize = candidates.reduce((sum, c) => sum + c.size, 0);
-  console.log(`\n🧹 Prune candidates — ${candidates.length} repo(s), ${formatSize(totalSize)} total:\n`);
-  for (const c of candidates) {
-    console.log(`   ${c.repoRel} (${formatSize(c.size)})`);
+  if (plan.candidates.length === 0) {
+    console.log('✅ All cold pool repositories are referenced. Nothing to prune.')
+    process.exit(0)
   }
 
-  // ── 确认 ────────────────────────────────────────────────────
-
-  let shouldDelete = false;
+  // ── Confirm ──────────────────────────────────────────────────────
+  let shouldDelete = false
   if (yes) {
-    shouldDelete = true;
-    console.log("\n⚠️  --yes flag set: deleting without confirmation.");
+    shouldDelete = true
+    console.log('\n⚠️  --yes flag set: deleting without confirmation.')
   } else {
-    shouldDelete = await confirm(`\nDelete ${candidates.length} unreferenced repo(s)?`);
+    shouldDelete = await confirm(`\nDelete ${plan.candidates.length} unreferenced repo(s)?`)
   }
 
   if (!shouldDelete) {
-    console.log("❎ Prune cancelled.");
-    process.exit(0);
-  }
-
-  // ── 执行删除 ────────────────────────────────────────────────
-
-  let deleted = 0;
-  let failed = 0;
-  for (const c of candidates) {
-    try {
-      rmSync(c.repoPath, { recursive: true, force: true });
-      console.log(`  🗑️  Deleted: ${c.repoRel}`);
-      deleted++;
-    } catch (err: any) {
-      console.error(`  ❌ Failed to delete ${c.repoRel}: ${err.message}`);
-      failed++;
-    }
+    console.log('❎ Prune cancelled.')
+    process.exit(0)
   }
 
-  console.log(`\n📦 Prune complete: ${deleted} deleted, ${failed} failed`);
+  // ── Execute with real IO ──────────────────────────────────────────
+  const results = executePrunePlan(plan, {
+    delete: (path: string) => rmSync(path, { recursive: true, force: true }),
+    log: console.log,
+    formatSize,
+  })
 
-  if (failed > 0) {
-    process.exit(1);
-  }
+  if (results.some(r => !r.deleted)) process.exit(1)
 }

package/src/refresh-plan.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect } from 'bun:test'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveRefreshConfig, detectGitRoot, buildRefreshPlan } from './refresh-plan'
+
+const deckAliasDict = `[deck]
+max_cards = 10
+cold_pool = "./cold-pool"
+
+[tool.skills.skill-a]
+path = "github.com/foo/bar/skill-a"
+
+[tool.skills.skill-b]
+path = "localhost/skill-b"
+`
+
+describe('resolveRefreshConfig', () => {
+  test('returns strings without throwing when no opts', () => {
+    const cfg = resolveRefreshConfig()
+    expect(typeof cfg.deckPath).toBe('string')
+    expect(typeof cfg.workdir).toBe('string')
+    expect(typeof cfg.coldPool).toBe('string')
+  })
+
+  test('resolves explicit deckPath', () => {
+    const cfg = resolveRefreshConfig({ deckPath: '/tmp/test-deck.toml' })
+    expect(cfg.deckPath).toBe('/tmp/test-deck.toml')
+  })
+
+  test('workdir falls back to deckPath dirname', () => {
+    const cfg = resolveRefreshConfig({ deckPath: '/tmp/my-deck.toml' })
+    expect(cfg.workdir).toBe('/tmp')
+  })
+
+  test('explicit workdir overrides fallback', () => {
+    const cfg = resolveRefreshConfig({ deckPath: '/tmp/my-deck.toml', workdir: '/custom/workdir' })
+    expect(cfg.workdir).toBe('/custom/workdir')
+  })
+
+  test('explicit coldPool resolved', () => {
+    const cfg = resolveRefreshConfig({ coldPool: '/custom/cold-pool' })
+    expect(cfg.coldPool).toBe('/custom/cold-pool')
+  })
+})
+
+describe('detectGitRoot', () => {
+  test('localhost skill → localhost type', () => {
+    const result = detectGitRoot('/pool/localhost/skill-a', '/pool')
+    expect(result.type).toBe('localhost')
+  })
+
+  test('localhost as root → localhost type', () => {
+    const result = detectGitRoot('/pool/localhost', '/pool')
+    expect(result.type).toBe('localhost')
+  })
+
+  test('not-git: directory without .git', () => {
+    const dir = join('/tmp', 'refresh-test-no-git-' + Date.now())
+    mkdirSync(dir, { recursive: true })
+    const result = detectGitRoot(dir, '/tmp')
+    expect(result.type).toBe('not-git')
+    rmSync(dir, { recursive: true, force: true })
+  })
+})
+
+describe('buildRefreshPlan', () => {
+  test('builds plan from alias-dict deck', () => {
+    const plan = buildRefreshPlan(deckAliasDict, { coldPool: '/tmp/test-cold-pool' })
+    expect(plan.targets).toHaveLength(2)
+    expect(plan.allDeclared).toHaveLength(2)
+  })
+
+  test('filters by alias when target specified', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      coldPool: '/tmp/test-cold-pool',
+      target: 'skill-a',
+    })
+    expect(plan.targets).toHaveLength(1)
+    expect(plan.targets[0].alias).toBe('skill-a')
+  })
+
+  test('filters by path when target specified', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      coldPool: '/tmp/test-cold-pool',
+      target: 'github.com/foo/bar/skill-a',
+    })
+    expect(plan.targets).toHaveLength(1)
+    expect(plan.targets[0].path).toBe('github.com/foo/bar/skill-a')
+  })
+
+  test('unknown target → empty plan', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      coldPool: '/tmp/test-cold-pool',
+      target: 'nonexistent',
+    })
+    expect(plan.targets).toHaveLength(0)
+  })
+
+  test('localhost skill is in plan as declared', () => {
+    const plan = buildRefreshPlan(deckAliasDict, { coldPool: '/tmp/test-cold-pool' })
+    const localhost = plan.targets.find(t => t.alias === 'skill-b')
+    // Without a real cold pool, source resolution may fail → 'missing'
+    // Plan structure is what matters; type depends on actual filesystem
+    expect(localhost).toBeDefined()
+    expect(localhost!.path).toBe('localhost/skill-b')
+  })
+
+  test('paths are resolved through config', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      deckPath: '/custom/deck.toml',
+      workdir: '/custom/work',
+      coldPool: '/custom/pool',
+    })
+    expect(plan.deckPath).toBe('/custom/deck.toml')
+    expect(plan.workdir).toBe('/custom/work')
+    expect(plan.coldPool).toBe('/custom/pool')
+  })
+})

package/src/refresh-plan.ts

@@ -0,0 +1,212 @@
+import { existsSync } from 'node:fs'
+import { resolve, dirname, relative } from 'node:path'
+import { realpathSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { findDeckToml, expandHome, findSource } from './link'
+import { parseDeck, type ParsedSkillEntry } from './parse-deck'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface RefreshTarget {
+  alias: string
+  path: string                      // FQ path
+  sourcePath: string                // absolute path in cold pool
+  sourceRel: string                 // relative to cold pool
+  type: 'git' | 'localhost' | 'missing' | 'not-git'
+  gitRoot?: string                  // populated for 'git' type
+}
+
+export interface RefreshPlan {
+  deckPath: string
+  workdir: string
+  coldPool: string
+  targets: RefreshTarget[]
+  allDeclared: ParsedSkillEntry[]
+}
+
+// ── Config resolution (pure, defaults via params) ──────────────────────────
+
+export function resolveRefreshConfig(opts?: {
+  deckPath?: string
+  workdir?: string
+  coldPool?: string
+}) {
+  const deckPath = opts?.deckPath
+    ? resolve(opts.deckPath)
+    : (findDeckToml(process.cwd()) || resolve('skill-deck.toml'))
+
+  const workdir = opts?.workdir
+    ? resolve(opts.workdir)
+    : dirname(deckPath)
+
+  const coldPool = opts?.coldPool
+    ? resolve(opts.coldPool)
+    : expandHome('~/.agents/skill-repos', workdir)
+
+  return { deckPath, workdir, coldPool }
+}
+
+// ── Git detection (pure: only checks directory structure, no mutation) ─────
+
+export function detectGitRoot(skillDir: string, coldPool: string): { gitRoot?: string; type: RefreshTarget['type'] } {
+  // localhost skills are user-managed
+  const rel = relative(coldPool, skillDir)
+  if (rel.startsWith('localhost') || rel === 'localhost') {
+    return { type: 'localhost' }
+  }
+
+  // Standalone skill: .git directly in skill dir
+  if (existsSync(resolve(skillDir, '.git'))) {
+    return { gitRoot: skillDir, type: 'git' }
+  }
+
+  try {
+    const out = execSync('git rev-parse --show-toplevel', {
+      cwd: skillDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim()
+
+    // Normalize paths (macOS /tmp → /private/tmp)
+    const resolvedRoot = realpathSync(out)
+    const resolvedDir = realpathSync(skillDir)
+    const resolvedPool = realpathSync(coldPool)
+
+    // Must be ancestor of skillDir and within coldPool
+    if (resolvedDir.startsWith(resolvedRoot + '/') &&
+        (resolvedRoot === resolvedPool || resolvedRoot.startsWith(resolvedPool + '/'))) {
+      return { gitRoot: out, type: 'git' }
+    }
+  } catch {}
+
+  return { type: 'not-git' }
+}
+
+// ── Plan builder (pure: no git pull, no mutation) ──────────────────────────
+
+export function buildRefreshPlan(
+  deckRaw: string,
+  opts?: { deckPath?: string; workdir?: string; coldPool?: string; target?: string }
+): RefreshPlan {
+  const { deckPath, workdir, coldPool: configuredColdPool } = resolveRefreshConfig(opts)
+
+  // Read cold_pool from deck.toml [deck] section if not explicitly overridden
+  let coldPool = configuredColdPool
+  if (!opts?.coldPool) {
+    const deckMatch = deckRaw.match(/cold_pool\s*=\s*"([^"]+)"/)
+    if (deckMatch) {
+      coldPool = expandHome(deckMatch[1], workdir)
+    }
+  }
+
+  const { entries: allDeclared } = parseDeck(deckRaw)
+
+  // Filter to target (by alias or path) if specified
+  let declared = allDeclared
+  if (opts?.target) {
+    const byAlias = allDeclared.find(d => d.alias === opts.target)
+    if (byAlias) {
+      declared = [byAlias]
+    } else {
+      const byPath = allDeclared.find(d => d.path === opts.target)
+      if (byPath) {
+        declared = [byPath]
+      } else {
+        declared = [] // target not found → empty plan
+      }
+    }
+  }
+
+  const targets: RefreshTarget[] = []
+
+  for (const entry of declared) {
+    const source = findSource(entry.path, coldPool, workdir)
+
+    if (source.error || !source.path) {
+      targets.push({ alias: entry.alias, path: entry.path, sourcePath: '', sourceRel: '', type: 'missing' })
+      continue
+    }
+
+    const { gitRoot, type } = detectGitRoot(source.path, coldPool)
+    const sourceRel = relative(coldPool, source.path)
+
+    targets.push({
+      alias: entry.alias,
+      path: entry.path,
+      sourcePath: source.path,
+      sourceRel,
+      type,
+      gitRoot,
+    })
+  }
+
+  return { deckPath, workdir, coldPool, targets, allDeclared }
+}
+
+// ── Execution (IO layer, injectable for testing) ───────────────────────────
+
+export interface RefreshResult {
+  alias: string
+  path: string
+  status: 'updated' | 'up-to-date' | 'skipped' | 'failed' | 'not-git'
+  message?: string
+}
+
+export interface RefreshIO {
+  gitPull?: (dir: string) => { status: 'updated' | 'up-to-date' | 'failed'; message: string }
+  log?: (msg: string) => void
+  linkDeck?: (deckPath?: string, workdir?: string) => void
+}
+
+export function executeRefreshPlan(plan: RefreshPlan, io?: RefreshIO): RefreshResult[] {
+  const gitPull = io?.gitPull ?? (() => ({ status: 'failed' as const, message: 'gitPull not injected' }))
+  const log = io?.log ?? (() => {})
+
+  const results: RefreshResult[] = []
+  let updated = 0, upToDate = 0, skipped = 0, failed = 0
+
+  for (const t of plan.targets) {
+    switch (t.type) {
+      case 'missing':
+        results.push({ alias: t.alias, path: '', status: 'failed', message: 'Skill not found in cold pool' })
+        failed++
+        break
+      case 'localhost':
+        results.push({ alias: t.alias, path: t.sourceRel, status: 'skipped', message: 'localhost skill — user-managed' })
+        skipped++
+        break
+      case 'not-git':
+        results.push({ alias: t.alias, path: t.sourceRel, status: 'not-git', message: 'skipped: not a git repository' })
+        skipped++
+        break
+      case 'git': {
+        const pullResult = gitPull(t.gitRoot!)
+        results.push({ alias: t.alias, path: t.sourceRel, status: pullResult.status, message: pullResult.message })
+        if (pullResult.status === 'updated') updated++
+        else if (pullResult.status === 'up-to-date') upToDate++
+        else failed++
+        break
+      }
+    }
+  }
+
+  // Report phase
+  const scope = plan.targets.length === plan.allDeclared.length
+    ? `${plan.allDeclared.length} skill(s)`
+    : 'single skill'
+  log(`\n📦 Skill Refresh Report — ${scope} checked`)
+  log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`)
+
+  for (const r of results) {
+    const icon = r.status === 'updated' ? '🔄' : r.status === 'up-to-date' ? '✅' :
+      r.status === 'skipped' ? '⏭️' : r.status === 'not-git' ? '📁' : '❌'
+    log(`${icon} ${r.alias}`)
+    if (r.message) log(`   ${r.message}`)
+  }
+
+  if (updated > 0) {
+    io?.linkDeck?.()
+  }
+
+  return results
+}

package/src/refresh.ts

@@ -7,12 +7,18 @@
  * Never modifies deck.toml.
  */
 
-import { parse as parseToml } from "@iarna/toml";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
-import { resolve, dirname, join, relative } from "node:path";
-import { findDeckToml, expandHome, findSource, linkDeck } from "./link.js";
+import { resolve } from "node:path";
+import { findDeckToml, linkDeck } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
+import { buildRefreshPlan, detectGitRoot, executeRefreshPlan } from "./refresh-plan.js";
+
+// Backward compat: old findGitRoot returns string|null
+export function findGitRoot(dir: string, coldPool: string): string | null {
+  const result = detectGitRoot(dir, coldPool)
+  return result.gitRoot ?? null
+}
 
 interface RefreshResult {
   name: string;
@@ -21,39 +27,6 @@ interface RefreshResult {
   message?: string;
 }
 
-export function findGitRoot(dir: string, coldPool: string): string | null {
-  // Standalone skill: .git directly in skill dir
-  if (existsSync(join(dir, ".git"))) {
-    return dir;
-  }
-
-  try {
-    const out = execSync("git rev-parse --show-toplevel", {
-      cwd: dir,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
-
-    const resolvedRoot = realpathSync(out);
-    const resolvedDir = realpathSync(dir);
-    const resolvedColdPool = realpathSync(coldPool);
-
-    // Must be an ancestor of dir (standalone case handled above)
-    if (!resolvedDir.startsWith(resolvedRoot + "/")) {
-      return null;
-    }
-
-    // Must be within cold_pool — prevents finding an unrelated git repo outside
-    if (resolvedRoot === resolvedColdPool || resolvedRoot.startsWith(resolvedColdPool + "/")) {
-      return out;
-    }
-
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; message: string } {
   try {
     const output = execSync("git pull", {
@@ -74,140 +47,54 @@ function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; me
 }
 
 export function refreshDeck(cliDeckPath?: string, cliWorkdir?: string, target?: string): void {
-  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
-  const DECK_PATH = cliDeck
-    ? resolve(cliDeck)
-    : findDeckToml(process.cwd()) || resolve("skill-deck.toml");
+  const deckPath = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
+  const workdir = cliWorkdir
+
+  const DECK_PATH = deckPath ? resolve(deckPath) : findDeckToml(process.cwd()) || resolve('skill-deck.toml')
 
   if (!existsSync(DECK_PATH)) {
-    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`);
-    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
-    process.exit(1);
+    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`)
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`)
+    process.exit(1)
   }
 
-  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
-  const deckRaw = readFileSync(DECK_PATH, "utf-8");
-  const deck = parseToml(deckRaw) as any;
-
-  const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+  const deckRaw = readFileSync(DECK_PATH, 'utf-8')
 
-  // ── 收集声明 ────────────────────────────────────────────────
+  // ── Plan: pure target collection + type classification ─────────────
+  const plan = buildRefreshPlan(deckRaw, {
+    deckPath: DECK_PATH,
+    workdir: workdir ? resolve(workdir) : undefined,
+    coldPool: undefined, // derive from deck
+    target,
+  })
 
-  const declared: { name: string; alias: string; path: string; type: string }[] = [];
-
-  // Use parseDeck for alias-dict compatibility
-  const { entries: parsedEntries, deprecated: isDeprecated } = parseDeck(deckRaw);
+  const { entries: parsedEntries, deprecated: isDeprecated } = parseDeck(deckRaw)
   if (isDeprecated) {
-    console.warn("⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
+    console.warn('⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.')
   }
 
-  for (const entry of parsedEntries) {
-    declared.push({ name: entry.path, alias: entry.alias, path: entry.path, type: entry.type });
+  if (parsedEntries.length === 0) {
+    console.log('📭 No skills declared in deck. Nothing to refresh.')
+    process.exit(0)
   }
 
-  if (declared.length === 0) {
-    console.log("📭 No skills declared in deck. Nothing to refresh.");
-    process.exit(0);
+  if (target && plan.targets.length === 0) {
+    console.error(`❌ Skill not found in deck: ${target}`)
+    const { entries } = parseDeck(deckRaw)
+    console.error(`   Declared aliases: ${entries.map(d => d.alias).join(', ')}`)
+    process.exit(1)
   }
 
-  // ── 确定目标 ────────────────────────────────────────────────
-
-  let targets: { name: string; alias: string; path: string; type: string }[];
-
-  if (target) {
-    // Try resolve as alias first, then as FQ path
-    const byAlias = declared.find(d => d.alias === target);
-    if (byAlias) {
-      targets = [byAlias];
-    } else {
-      const byPath = declared.find(d => d.path === target);
-      if (byPath) {
-        targets = [byPath];
-      } else {
-        console.error(`❌ Skill not found in deck: ${target}`);
-        console.error(`   Declared aliases: ${declared.map(d => d.alias).join(", ")}`);
-        process.exit(1);
-      }
-    }
-  } else {
-    targets = declared;
-  }
-
-  // ── 执行刷新 ────────────────────────────────────────────────
-
-  const results: RefreshResult[] = [];
-  let updated = 0;
-  let upToDate = 0;
-  let skipped = 0;
-  let failed = 0;
-
-  for (const item of targets) {
-    const result = findSource(item.path, COLD_POOL, PROJECT_DIR);
-
-    if (result.error || !result.path) {
-      results.push({ name: item.alias, path: "", status: "failed", message: result.error || "Skill not found in cold pool" });
-      failed++;
-      continue;
-    }
-
-    const path = result.path;
-
-    // localhost skills are user-managed; skip
-    const relativePath = relative(COLD_POOL, path);
-    if (relativePath.startsWith("localhost")) {
-      results.push({ name: item.alias, path: relativePath, status: "skipped", message: "localhost skill — user-managed" });
-      skipped++;
-      continue;
-    }
-
-    const gitRoot = findGitRoot(path, COLD_POOL);
-    if (!gitRoot) {
-      results.push({ name: item.alias, path: relativePath, status: "not-git", message: "skipped: not a git repository" });
-      skipped++;
-      continue;
-    }
-
-    const pullResult = gitPull(gitRoot);
-    results.push({ name: item.alias, path: relativePath, status: pullResult.status, message: pullResult.message });
-
-    if (pullResult.status === "updated") updated++;
-    else if (pullResult.status === "up-to-date") upToDate++;
-    else failed++;
-  }
-
-  // ── 报告 ────────────────────────────────────────────────────
-
-  const scope = target ? `single skill` : `${declared.length} skill(s)`;
-  console.log(`\n📦 Skill Refresh Report — ${scope} checked`);
-  console.log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`);
-  console.log();
-
-  for (const r of results) {
-    const icon =
-      r.status === "updated" ? "🔄" :
-      r.status === "up-to-date" ? "✅" :
-      r.status === "skipped" ? "⏭️" :
-      r.status === "not-git" ? "📁" :
-      "❌";
-    console.log(`${icon} ${r.name}`);
-    if (r.message && r.status !== "up-to-date") {
-      const lines = r.message.split("\n").filter(l => l.trim());
-      for (const line of lines.slice(0, 3)) {
-        console.log(`   ${line.trim()}`);
-      }
-      if (lines.length > 3) {
-        console.log(`   ... (${lines.length - 3} more lines)`);
-      }
-    }
-  }
-
-  if (updated > 0) {
-    console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync refreshed skills to working set.`);
-    console.log("🔗 Running deck link...");
-    linkDeck(cliDeckPath, cliWorkdir);
-  }
-
-  if (failed > 0) {
-    process.exit(1);
-  }
+  // ── Execute with real IO ────────────────────────────────────
+  const results = executeRefreshPlan(plan, {
+    gitPull,
+    log: console.log,
+    linkDeck: () => {
+      console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync refreshed skills to working set.`)
+      console.log('🔗 Running deck link...')
+      linkDeck(cliDeckPath, cliWorkdir)
+    },
+  })
+
+  if (results.some(r => r.status === 'failed')) process.exit(1)
 }