@lythos/cold-pool 0.14.3 → 0.14.4

package/README.md

@@ -31,7 +31,7 @@ Three layers, sharing the project's `intent → plan → execute` pattern
 Per `ADR-20260502012643244`, locators are FQ-only:
 
 - `host.tld/owner/repo[/skill]` — remote skill (monorepo, flat, or arbitrary subdir)
-- `localhost/<name>` — local-only skill, no remote origin
+- `localhost/me/<skill>` — local-only skill, no remote origin (host/owner/repo aligned)
 
 Bare names and `owner/repo` shorthand are rejected — `parseLocator` returns null.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "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.14.3",
+    "@lythos/infra": "^0.14.4",
     "simple-git": "^3.36.0"
   },
   "engines": {

package/src/cold-pool.ts

@@ -40,6 +40,7 @@ export interface ListPlan {
  * directory. Terminal-depth heuristics alone miss real-world layouts
  * like monorepos with subdirs, multi-skill repos, and mixed-depth clones.
  */
+/** Pure plan builder — IO (readdirSync) done by caller, results injected as allEntries. */
 export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPlan {
   const plan: ListPlanEntry[] = []
   const dirSet = new Set(allEntries.filter(e => e.isDirectory).map(e => e.relPath))

package/src/fetch-plan.ts

@@ -16,6 +16,7 @@ import type { Locator, FetchPlan, FetchResult, FetchIO } from './types.js'
 import { gitClone } from './git-io.js'
 import { getMirror, rewriteUrl } from './mirror.js'
 
+/** Plan builder — IO via ColdPool parameter (pool.has, pool.resolveDir). Execute: executeFetchPlan(plan, io?) in same file. Mock ColdPool for plan-mode tests. */
 export function buildFetchPlan(
   pool: ColdPool,
   locator: Locator,

package/src/parse-locator.test.ts

@@ -110,7 +110,7 @@ describe('parseLocator — rejected forms (per ADR-20260502012643244 FQ-only)',
     expect(parseLocator('localhost')).toBeNull()
   })
 
-  test('localhost/<name> (single name, missing repo) is rejected — that was the post-compaction agent invention', () => {
+  test('localhost/<name> (2 segments) is rejected — use localhost/me/<skill> for quick local form', () => {
     expect(parseLocator('localhost/my-skill')).toBeNull()
   })
 })

package/src/parse-locator.ts

@@ -1,19 +1,18 @@
 /**
  * FQ-only locator parser, per ADR-20260502012643244.
  *
- * Three accepted forms (everything else returns null):
+ * Accepted forms (everything else returns null):
  *   - `host.tld/owner/repo[/skill]`        — remote skill
  *   - `host.tld/owner/repo[/skill]#ref`    — remote skill at branch/tag/commit
  *   - `host.tld/owner/repo`                — remote standalone (skill = null)
- *   - `localhost/owner/repo[/skill]`       — local skill, same shape as remote
+ *   - `localhost/me/<skill>`               — local skill, full form (host/owner/repo aligned)
  *
  * The locator is a path. Appending it to the cold-pool base dir gives an
- * existing directory; SKILL.md inside is the skill content. No special-case
- * for localhost — only difference is `host === 'localhost'` signals "no
- * remote, no clone, no refresh".
+ * existing directory; SKILL.md inside is the skill content. For localhost,
+ * `host === 'localhost'` signals "no remote, no clone, no refresh".
  *
- * Single-name `localhost/<name>` is rejected — that's a post-compaction
- * agent invention, not the canonical form.
+ * localhost follows the same host/owner/repo shape as remote locators —
+ * `me` is the conventional owner for personal skills.
  *
  * `#ref` suffix (branch/tag/commit) is compatible with skills.sh's
  * `parseFragmentRef`. The ref is passed to gitClone for checkout.
@@ -41,7 +40,8 @@ export function parseLocator(input: string): Locator | null {
   const parts = pathPart.split('/')
   // Reject empty segments (double slashes) and path traversal
   if (parts.some(p => p === '' || p === '..' || p === '.')) return null
-  // Need at least host/owner/repo (3 segments) for any FQ form
+  // Need at least host/owner/repo (3 segments) for any FQ form.
+  // For localhost quick form, use: localhost/me/<skill-name>
   if (parts.length < 3) return null
 
   // host segment: must be `localhost` (literal) or contain a `.` (host.tld)

package/src/prune-plan.test.ts

@@ -0,0 +1,124 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { buildPrunePlan, executePrunePlan } from './prune-plan'
+import { ColdPool } from './cold-pool'
+
+function seedPool(): { root: string; pool: ColdPool } {
+  const root = mkdtempSync(join(tmpdir(), 'prune-test-'))
+  const pool = new ColdPool(root)
+
+  // Repo A: referenced → should NOT be pruned
+  const repoA = join(root, 'github.com', 'org', 'repo-a')
+  mkdirSync(repoA, { recursive: true })
+  writeFileSync(join(repoA, 'SKILL.md'), '# Skill A')
+
+  // Repo B: NOT referenced → SHOULD be pruned
+  const repoB = join(root, 'github.com', 'org', 'repo-b')
+  mkdirSync(repoB, { recursive: true })
+  writeFileSync(join(repoB, 'SKILL.md'), '# Skill B')
+
+  // Repo C: referenced → should NOT be pruned
+  const repoC = join(root, 'github.com', 'org', 'repo-c')
+  mkdirSync(repoC, { recursive: true })
+  writeFileSync(join(repoC, 'SKILL.md'), '# Skill C')
+
+  // Seed metadata: A and C are active, B is not
+  pool.metadata.reconcileDeckReferences('/tmp/test-deck', [
+    { locator: 'github.com/org/repo-a', alias: 'a' },
+    { locator: 'github.com/org/repo-c', alias: 'c' },
+  ])
+
+  return { root, pool }
+}
+
+describe('buildPrunePlan — plan-mode (IO via ColdPool + test filesystem)', () => {
+  let root: string
+  let pool: ColdPool
+
+  beforeEach(() => {
+    const p = seedPool()
+    root = p.root
+    pool = p.pool
+  })
+
+  afterEach(() => {
+    try { pool.metadata.close() } catch {}
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  test('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', () => {
+    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', () => {
+    const emptyDir = mkdtempSync(join(tmpdir(), 'prune-empty-'))
+    const plan = buildPrunePlan(emptyDir)
+    expect(plan.candidates).toEqual([])
+    expect(plan.totalSize).toBe(0)
+    rmSync(emptyDir, { recursive: true, force: true })
+  })
+
+  test('plan includes coldPoolPath and totalSize', () => {
+    const plan = buildPrunePlan(root)
+    expect(plan.coldPoolPath).toBe(root)
+    expect(plan.totalSize).toBeGreaterThan(0)
+  })
+})
+
+describe('executePrunePlan — plan-mode (IO injected)', () => {
+  test('calls delete for each candidate', () => {
+    const deleted: string[] = []
+    const plan = {
+      coldPoolPath: '/pool',
+      candidates: [
+        { repoPath: '/pool/gh/org/a', repoRel: 'gh/org/a', size: 1024 },
+        { repoPath: '/pool/gh/org/b', repoRel: 'gh/org/b', size: 2048 },
+      ],
+      totalSize: 3072,
+    }
+    const results = executePrunePlan(plan, {
+      delete: (path) => { deleted.push(path) },
+      log: () => {},
+    })
+    expect(deleted).toEqual(['/pool/gh/org/a', '/pool/gh/org/b'])
+    expect(results).toHaveLength(2)
+    expect(results[0].deleted).toBe(true)
+    expect(results[1].deleted).toBe(true)
+  })
+
+  test('logs count and total size', () => {
+    const logs: string[] = []
+    executePrunePlan({
+      coldPoolPath: '/pool',
+      candidates: [{ repoPath: '/pool/x', repoRel: 'x', size: 500 }],
+      totalSize: 500,
+    }, {
+      delete: () => {},
+      log: (msg) => logs.push(msg),
+    })
+    const joined = logs.join(' ')
+    expect(joined).toContain('1 repo')
+    expect(joined).toContain('500')
+  })
+
+  test('skips delete when candidates array empty', () => {
+    let called = false
+    const results = executePrunePlan(
+      { coldPoolPath: '/pool', candidates: [], totalSize: 0 },
+      { delete: () => { called = true }, log: () => {} },
+    )
+    expect(called).toBe(false)
+    expect(results).toEqual([])
+  })
+})

package/src/prune-plan.ts

@@ -82,6 +82,7 @@ function defaultFormatSize(bytes: number): string {
  * 2. Queries metadata DB for all active locators (state = added/linked/NULL).
  * 3. A repo is prunable if no active locator references it.
  */
+/** Plan builder — IO via ColdPool (findSkillDirectories, metadata queries). Execute: executePrunePlan(plan, io?) in same file. Mock ColdPool for plan-mode tests. */
 export function buildPrunePlan(coldPoolPath: string): PrunePlan {
   const pool = new ColdPool(coldPoolPath)
   const allRepos = pool.findSkillDirectories()

package/src/reconcile-plan.ts

@@ -66,6 +66,7 @@ function extractRepo(source: string): RepoKey | null {
 
 // ── Plan builder ───────────────────────────────────────────────────────────
 
+/** Plan builder — IO via ColdPool parameter (list, has, metadata). Execute: executeReconcilePlan(plan, io?) in same file. Mock ColdPool for plan-mode tests. */
 export function buildReconcilePlan(
   coldPool: ColdPool,
   desired: ReconcileDesiredState,

package/src/types.ts

@@ -11,9 +11,10 @@
  *   - `host.tld/owner/repo` (remote standalone — repo root has SKILL.md, skill = null)
  *   - `localhost/owner/repo[/skill]` (no remote — same shape, host literal `localhost`)
  *
- * Bare names, shorthand `owner/repo`, and `localhost/<name>` (no owner/repo)
- * are rejected by `parseLocator`. The locator is a path: appending to coldPool
- * yields `<coldPool>/<host>/<owner>/<repo>[/skill]/SKILL.md`. The only thing
+ * Bare names and shorthand `owner/repo` are rejected by `parseLocator`.
+ * localhost follows host/owner/repo shape: `localhost/me/<skill>`.
+ * The locator is a path: appending to coldPool yields
+ * `<coldPool>/<host>/<owner>/<repo>[/skill]/SKILL.md`. The only thing
  * `isLocalhost` controls is "no remote operations" (no clone, no pull, no fetch).
  */
 export interface Locator {

package/src/validate-plan.ts

@@ -32,6 +32,7 @@ export interface ValidationIO {
 
 const DEFAULT_CHECKS: ValidationCheck[] = ['syntax', 'remote', 'path']
 
+/** Pure plan builder. Execute: executeValidationPlan(plan, io?) in same file — IO injected via ValidationIO. */
 export function buildValidationPlan(
   rawInput: string,
   opts?: { checks?: ReadonlyArray<ValidationCheck>; ref?: string },
@@ -55,7 +56,7 @@ export async function executeValidationPlan(
     fixes.push({
       action: 'update-locator',
       confidence: 0.5,
-      message: 'Locator must be FQ: host.tld/owner/repo[/skill] or localhost/<name>. Bare names are rejected per ADR-20260502012643244.',
+      message: 'Locator must be FQ: host.tld/owner/repo[/skill] or localhost/me/<skill>. Bare names are rejected per ADR-20260502012643244.',
     })
     return {
       status: 'invalid',