@lythos/cold-pool 0.9.28 → 0.9.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.9.28",
+  "version": "0.9.30",
   "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",

package/src/cold-pool.test.ts

@@ -2,9 +2,12 @@ import { describe, expect, test } from 'bun:test'
 import { mkdirSync, mkdtempSync, writeFileSync, existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool'
+import { ColdPool, DEFAULT_COLD_POOL_PATH, buildListPlan, type DirEntry } from './cold-pool'
 import { parseLocator } from './parse-locator'
 
+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', () => {
     const pool = new ColdPool()
@@ -100,6 +103,113 @@ describe('ColdPool — fs-backed read accessors', () => {
   })
 })
 
+describe('buildListPlan — pure classification (no IO)', () => {
+  const root = '/pool'
+
+  test('canonical 3-segment: host/owner/repo', () => {
+    const entries: DirEntry[] = [
+      dir('github.com'),
+      dir('github.com/owner'),
+      dir('github.com/owner/repo-a'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toEqual([
+      { path: '/pool/github.com/owner/repo-a', kind: 'canonical' },
+    ])
+  })
+
+  test('skips hidden dirs', () => {
+    const entries: DirEntry[] = [
+      dir('.git'),
+      dir('github.com'),
+      dir('github.com/owner'),
+      dir('github.com/owner/repo-a'),
+      dir('github.com/owner/.DS_Store'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toEqual([
+      { path: '/pool/github.com/owner/repo-a', kind: 'canonical' },
+    ])
+  })
+
+  test('legacy depth-1: host/SKILL.md (missing owner+repo)', () => {
+    const entries: DirEntry[] = [
+      dir('legacy-skill'),
+      file('legacy-skill/SKILL.md'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toEqual([
+      { path: '/pool/legacy-skill', kind: 'legacy-depth1' },
+    ])
+  })
+
+  test('legacy depth-2: localhost/name/SKILL.md (missing repo)', () => {
+    const entries: DirEntry[] = [
+      dir('localhost'),
+      dir('localhost/legacy-name'),
+      file('localhost/legacy-name/SKILL.md'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toEqual([
+      { path: '/pool/localhost/legacy-name', kind: 'legacy-depth2' },
+    ])
+  })
+
+  test('mixed canonical + legacy in same pool', () => {
+    const entries: DirEntry[] = [
+      dir('github.com'),
+      dir('github.com/owner'),
+      dir('github.com/owner/repo-a'),
+      dir('localhost'),
+      dir('localhost/old-skill'),
+      file('localhost/old-skill/SKILL.md'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toHaveLength(2)
+    expect(plan.entries).toContainEqual({ path: '/pool/github.com/owner/repo-a', kind: 'canonical' })
+    expect(plan.entries).toContainEqual({ path: '/pool/localhost/old-skill', kind: 'legacy-depth2' })
+  })
+
+  test('multiple repos under same owner', () => {
+    const entries: DirEntry[] = [
+      dir('github.com'),
+      dir('github.com/owner'),
+      dir('github.com/owner/repo-a'),
+      dir('github.com/owner/repo-b'),
+      dir('github.com/owner/repo-c'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toHaveLength(3)
+    expect(plan.entries.every(e => e.kind === 'canonical')).toBe(true)
+  })
+
+  test('multiple hosts', () => {
+    const entries: DirEntry[] = [
+      dir('github.com'),
+      dir('github.com/a'),
+      dir('github.com/a/r1'),
+      dir('gitlab.com'),
+      dir('gitlab.com/b'),
+      dir('gitlab.com/b/r2'),
+    ]
+    const plan = buildListPlan(root, entries)
+    expect(plan.entries).toHaveLength(2)
+    expect(plan.entries.map(e => e.path).sort()).toEqual([
+      '/pool/github.com/a/r1',
+      '/pool/gitlab.com/b/r2',
+    ])
+  })
+
+  test('returns empty when root has no entries', () => {
+    expect(buildListPlan(root, []).entries).toEqual([])
+  })
+
+  test('returns empty for hidden-only entries', () => {
+    const entries: DirEntry[] = [dir('.git'), dir('.hidden/.nested')]
+    expect(buildListPlan(root, entries).entries).toEqual([])
+  })
+})
+
 describe('ColdPool.metadata — MetadataDB integration', () => {
   const root = mkdtempSync(join(tmpdir(), 'cold-pool-meta-test-'))
   const pool = new ColdPool(root)

package/src/cold-pool.ts

@@ -1,20 +1,91 @@
-/**
- * ColdPool — dedicated resource holder.
- *
- * Owns the cold-pool path, exposes read-only accessors. Operations
- * (fetch, validate, reconcile) are external functions that take a
- * ColdPool and return Plan-shaped data, per the intent/plan/execute
- * pattern.
- */
 import { existsSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 import type { Locator } from './types.js'
 import { MetadataDB } from './metadata-db.js'
 
 export const DEFAULT_COLD_POOL_PATH = process.env.LYTHOS_COLD_POOL
   ?? join(homedir(), '.agents/skill-repos')
 
+// ── DirEntry — pure, injectable fs entry ─────────────────────────────────────
+
+export interface DirEntry {
+  /** Path relative to cold-pool root (e.g. "github.com/owner/repo") */
+  relPath: string
+  isDirectory: boolean
+}
+
+// ── List plan: pure classification logic ────────────────────────────────────
+
+export interface ListPlanEntry {
+  path: string
+  kind: 'canonical' | 'legacy-depth2' | 'legacy-depth1'
+}
+
+export interface ListPlan {
+  entries: ListPlanEntry[]
+}
+
+/**
+ * Pure: given a cold-pool root path and a flat list of all fs entries
+ * (with relPath), classify every terminal repo directory.
+ *
+ * Canonical:  <pool>/<host>/<owner>/<repo>           (3 segments, no SKILL.md mid-tree)
+ * Legacy:     <pool>/<host>/SKILL.md                  (depth 1 — no owner/repo)
+ *             <pool>/<host>/<name>/SKILL.md            (depth 2 — no repo segment)
+ */
+export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPlan {
+  const plan: ListPlanEntry[] = []
+  const dirSet = new Set(allEntries.filter(e => e.isDirectory).map(e => e.relPath))
+
+  // Determine whether a dir is terminal (no child dirs)
+  function isTerminal(relPath: string): boolean {
+    const prefix = relPath + '/'
+    for (const d of dirSet) {
+      if (d.startsWith(prefix) && d !== relPath) return false
+    }
+    return true
+  }
+
+  // Check whether a dir directly contains SKILL.md
+  function hasSkillMd(dirRel: string): boolean {
+    return allEntries.some(e => e.relPath === `${dirRel}/SKILL.md` && !e.isDirectory)
+  }
+
+  // Walk only terminal dirs — they are the leaves (repo-level entries)
+  for (const d of dirSet) {
+    if (d.startsWith('.') || d.split('/').some(s => s.startsWith('.'))) continue
+    if (!isTerminal(d)) continue
+
+    const segments = d.split('/')
+
+    // Legacy depth-1: <host>/SKILL.md — terminal dir with SKILL.md, depth=1
+    if (segments.length === 1 && hasSkillMd(d)) {
+      plan.push({ path: join(rootPath, d), kind: 'legacy-depth1' })
+      continue
+    }
+
+    // Legacy depth-2: <host>/<name>/SKILL.md — terminal dir with SKILL.md, depth=2
+    if (segments.length === 2 && hasSkillMd(d)) {
+      plan.push({ path: join(rootPath, d), kind: 'legacy-depth2' })
+      continue
+    }
+
+    // Canonical: <host>/<owner>/<repo> — terminal dir at depth 3, no SKILL.md mid-tree
+    if (segments.length === 3) {
+      // Verify no SKILL.md at intermediate levels (depth 1 or 2)
+      const parent = segments.slice(0, 2).join('/')
+      if (!hasSkillMd(segments[0]) && !hasSkillMd(parent)) {
+        plan.push({ path: join(rootPath, d), kind: 'canonical' })
+      }
+    }
+  }
+
+  return { entries: plan }
+}
+
+// ── ColdPool ─────────────────────────────────────────────────────────────────
+
 export class ColdPool {
   readonly path: string
   readonly metadata: MetadataDB
@@ -24,67 +95,38 @@ export class ColdPool {
     this.metadata = new MetadataDB(join(this.path, '.cold-pool-meta.db'))
   }
 
-  /**
-   * Compute the cold-pool directory for a locator. No fs check.
-   *
-   * Layout invariant: `<pool>/<host>/<owner>/<repo>` for ALL locators
-   * including localhost. No special-case branching — "directory layers
-   * = FQ locator segments" (per user 2026-05-07). Skill subpath
-   * extends within the repo dir (resolveDir returns the repo dir).
-   */
   resolveDir(locator: Locator): string {
     return join(this.path, locator.host, locator.owner, locator.repo)
   }
 
-  /** Whether a locator's repo directory exists in the pool. */
   has(locator: Locator): boolean {
     return existsSync(this.resolveDir(locator))
   }
 
-  /**
-   * Enumerate cold-pool entries.
-   *
-   * Uniform layout: `<pool>/<host>/<owner>/<repo>`. localhost is just
-   * another host. No localhost special-case.
-   *
-   * Legacy drift: `<pool>/<x>/SKILL.md` (depth 2 with SKILL.md) or
-   * `<pool>/localhost/<name>/SKILL.md` (depth 3 with SKILL.md, missing
-   * owner/repo) are non-canonical state from older agents that bypassed
-   * FQ-only enforcement. Surface them so prune can offer cleanup.
-   */
+  /** Enumerate cold-pool entries. Delegates classification to pure buildListPlan. */
   list(): string[] {
     if (!existsSync(this.path)) return []
-    const repos: string[] = []
-
-    for (const host of readdirSync(this.path, { withFileTypes: true })) {
-      if (!host.isDirectory() || host.name.startsWith('.')) continue
-      const hostPath = join(this.path, host.name)
 
-      // Legacy drift: top-level dir with SKILL.md (not canonical 3-segment)
-      if (existsSync(join(hostPath, 'SKILL.md'))) {
-        repos.push(hostPath)
-        continue
+    const poolPath = this.path
+    const allEntries: DirEntry[] = []
+    function collectRecursive(dir: string): void {
+      let dirents: ReturnType<typeof readdirSync>
+      try {
+        dirents = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        return
       }
-
-      // Canonical: <host>/<owner>/<repo>
-      for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
-        if (!owner.isDirectory() || owner.name.startsWith('.')) continue
-        const ownerPath = join(hostPath, owner.name)
-
-        // Legacy drift: <host>/<x>/SKILL.md (depth 2 missing repo level —
-        // typically `localhost/<name>/SKILL.md` from older agents)
-        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))
+      for (const d of dirents) {
+        const rel = relative(poolPath, join(dir, d.name))
+        allEntries.push({ relPath: rel, isDirectory: d.isDirectory() })
+        if (d.isDirectory() && !d.name.startsWith('.')) {
+          collectRecursive(join(dir, d.name))
         }
       }
     }
+    collectRecursive(poolPath)
 
-    return repos
+    const plan = buildListPlan(poolPath, allEntries)
+    return plan.entries.map(e => e.path)
   }
 }

package/src/db-helpers.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared SQLite helpers — lazy-open, schema versioning, DRY wrappers.
+ *
+ * Used by MetadataDB (cold-pool) and curator's catalog DB.
+ * Consumers subclass and call super(dbPath) + define initSchema().
+ */
+import { Database } from 'bun:sqlite'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export abstract class SqliteDb {
+  protected abstract initSchema(): void
+
+  private dbPath: string
+  private _db: Database | null = null
+
+  constructor(dbPath: string) {
+    this.dbPath = dbPath
+  }
+
+  /** Lazy-open: first DB access triggers creation. */
+  protected get db(): Database {
+    if (this._db == null) {
+      try {
+        mkdirSync(dirname(this.dbPath), { recursive: true })
+      } catch {
+        // Parent dir may be read-only (e.g. test paths).
+      }
+      this._db = new Database(this.dbPath, { create: true })
+      this.initSchema()
+    }
+    return this._db
+  }
+
+  protected exec(sql: string, params?: Record<string, unknown>): void {
+    const stmt = this.db.query(sql)
+    stmt.run(params ?? {})
+    stmt.finalize()
+  }
+
+  protected queryOne<T>(sql: string, params?: Record<string, unknown>): T | null {
+    return this.db.query(sql).get(params ?? {}) as T | null
+  }
+
+  protected queryAll<T>(sql: string, params?: Record<string, unknown>): T[] {
+    return this.db.query(sql).all(params ?? {}) as T[]
+  }
+
+  /** Schema version tracking: call from initSchema() to auto-migrate. */
+  protected migrateSchema(currentVersion: number, migrations: Array<{ version: number; sql: string }>): void {
+    this.exec(`CREATE TABLE IF NOT EXISTS _schema_version (version INTEGER NOT NULL)`)
+    let row = this.queryOne<{ version: number }>(`SELECT version FROM _schema_version`)
+    let dbVersion = row?.version ?? 0
+
+    for (const m of migrations.sort((a, b) => a.version - b.version)) {
+      if (m.version > dbVersion) {
+        try {
+          this.db.query(m.sql).run()
+        } catch {
+          // Migration may fail if column already exists — fine for idempotent ADD COLUMN.
+        }
+        dbVersion = m.version
+      }
+    }
+
+    if (dbVersion !== (row?.version ?? 0)) {
+      this.exec(`DELETE FROM _schema_version`)
+      this.exec(`INSERT INTO _schema_version (version) VALUES ($v)`, { $v: dbVersion })
+    }
+  }
+
+  close(): void {
+    this._db?.close()
+    this._db = null
+  }
+}

package/src/git-hash.test.ts

@@ -11,6 +11,9 @@ beforeAll(async () => {
   repoDir = mkdtempSync(join(tmpdir(), 'lythos-git-hash-test-'))
   const git = simpleGit(repoDir)
   await git.init(['--initial-branch=main'])
+  // CI runners often lack git identity; set local config so commit works.
+  await git.addConfig('user.name', 'test')
+  await git.addConfig('user.email', 'test@test.com')
   writeFileSync(join(repoDir, 'SKILL.md'), '# Test Skill\n')
   mkdirSync(join(repoDir, 'skills', 'pdf'), { recursive: true })
   writeFileSync(join(repoDir, 'skills', 'pdf', 'SKILL.md'), '# PDF Skill\n> renders PDF\n')

package/src/index.ts

@@ -16,8 +16,10 @@ export type {
 } from './types.js'
 
 export { parseLocator, formatLocator } from './parse-locator.js'
-export { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool.js'
+export type { DirEntry, ListPlan, ListPlanEntry } from './cold-pool.js'
+export { ColdPool, DEFAULT_COLD_POOL_PATH, buildListPlan } from './cold-pool.js'
 
+export { SqliteDb } from './db-helpers.js'
 export type { RepoRef, SkillHash, DeckReference } from './metadata-db.js'
 export { MetadataDB } from './metadata-db.js'
 

package/src/metadata-db.ts

@@ -2,6 +2,7 @@
  * Cold-pool metadata layer — SQLite-backed.
  *
  * Per ADR-20260507143241493: git-native hash, local-only trust, SQLite storage.
+ * Extends shared SqliteDb base for DRY SQLite wrappers + schema versioning.
  *
  * Three tables:
  *   repos        — per-repo HEAD ref tracking
@@ -9,9 +10,7 @@
  *   deck_refs    — cross-deck reference index
  */
 
-import { Database } from 'bun:sqlite'
-import { mkdirSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { SqliteDb } from './db-helpers.js'
 
 export interface RepoRef {
   host: string
@@ -37,32 +36,14 @@ export interface DeckReference {
   declaredAlias: string | null
 }
 
-export class MetadataDB {
-  private dbPath: string
-  private _db: Database | null = null
+const CURRENT_SCHEMA = 2
 
+export class MetadataDB extends SqliteDb {
   constructor(dbPath: string) {
-    this.dbPath = dbPath
+    super(dbPath)
   }
 
-  /** Lazy-open: first DB access triggers creation. Allows ColdPool
-   *  to be instantiated with read-only / non-existent paths (e.g. test
-   *  fixtures) without failing on construction. */
-  private get db(): Database {
-    if (this._db == null) {
-      try {
-        mkdirSync(dirname(this.dbPath), { recursive: true })
-      } catch {
-        // Parent dir may be read-only (e.g. test paths like /cold).
-        // SQLite { create: true } will fail below with a clearer error.
-      }
-      this._db = new Database(this.dbPath, { create: true })
-      this.initSchema()
-    }
-    return this._db
-  }
-
-  private initSchema(): void {
+  protected initSchema(): void {
     this.exec(`
       CREATE TABLE IF NOT EXISTS repos (
         host TEXT NOT NULL,
@@ -100,25 +81,15 @@ export class MetadataDB {
     this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_deck ON deck_refs(deck_path)`)
     this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_locator ON deck_refs(skill_locator)`)
     this.exec(`CREATE INDEX IF NOT EXISTS idx_skills_repo ON skills(host, owner, repo)`)
-  }
-
-  // ── Small db util wrappers (no ORM, just DRY) ────────────────
-
-  /** Execute a statement that returns no rows. Auto-finalize. */
-  private exec(sql: string, params?: Record<string, unknown>): void {
-    const stmt = this.db.query(sql)
-    stmt.run(params ?? {})
-    stmt.finalize()
-  }
 
-  /** Query zero or one row. */
-  private queryOne<T>(sql: string, params?: Record<string, unknown>): T | null {
-    return this.db.query(sql).get(params ?? {}) as T | null
-  }
-
-  /** Query many rows. */
-  private queryAll<T>(sql: string, params?: Record<string, unknown>): T[] {
-    return this.db.query(sql).all(params ?? {}) as T[]
+    // Schema migrations
+    this.migrateSchema(CURRENT_SCHEMA, [
+      { version: 1, sql: `CREATE TABLE IF NOT EXISTS _schema_version (version INTEGER NOT NULL)` },
+      {
+        version: 2,
+        sql: `ALTER TABLE skills ADD COLUMN git_blob_hash TEXT`,
+      },
+    ])
   }
 
   private now(): string {
@@ -228,9 +199,4 @@ export class MetadataDB {
       insert.finalize()
     })()
   }
-
-  close(): void {
-    this._db?.close()
-    this._db = null
-  }
 }