@lythos/cold-pool 0.9.24

package/src/github-tree.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'bun:test'
+import { fetchRepoTree, type FetchFn, type TreeEntry } from './github-tree'
+
+function mockFetch(impl: (url: string, init?: RequestInit) => {
+  status: number
+  body?: unknown
+  headers?: Record<string, string>
+  error?: Error
+}): FetchFn {
+  return async (url, init) => {
+    const out = impl(url, init)
+    if (out.error) throw out.error
+    return new Response(out.body !== undefined ? JSON.stringify(out.body) : null, {
+      status: out.status,
+      headers: out.headers,
+    })
+  }
+}
+
+describe('fetchRepoTree', () => {
+  test('200 → ok with entries', async () => {
+    const entries: TreeEntry[] = [
+      { path: 'README.md', type: 'blob', sha: 'a' },
+      { path: 'skills/pdf/SKILL.md', type: 'blob', sha: 'b' },
+    ]
+    const fetch = mockFetch((url) => {
+      expect(url).toBe('https://api.github.com/repos/anthropics/skills/git/trees/HEAD?recursive=1')
+      return { status: 200, body: { tree: entries, truncated: false } }
+    })
+    const res = await fetchRepoTree('github.com', 'anthropics', 'skills', 'HEAD', fetch)
+    expect(res.status).toBe('ok')
+    expect(res.entries).toEqual(entries)
+    expect(res.httpStatus).toBe(200)
+    expect(res.truncated).toBe(false)
+  })
+
+  test('200 with truncated', async () => {
+    const fetch = mockFetch(() => ({
+      status: 200,
+      body: { tree: [], truncated: true },
+    }))
+    const res = await fetchRepoTree('github.com', 'o', 'r', 'HEAD', fetch)
+    expect(res.truncated).toBe(true)
+  })
+
+  test('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 () => {
+    const fetch = mockFetch(() => ({
+      status: 403,
+      headers: { 'X-RateLimit-Remaining': '0' },
+    }))
+    const res = await fetchRepoTree('github.com', 'o', 'r', 'HEAD', fetch)
+    expect(res.status).toBe('rate-limited')
+  })
+
+  test('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 () => {
+    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 () => {
+    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 () => {
+    let capturedUrl = ''
+    const fetch = mockFetch((url) => {
+      capturedUrl = url
+      return { status: 200, body: { tree: [] } }
+    })
+    await fetchRepoTree('github.com', 'o', 'r', undefined, fetch)
+    expect(capturedUrl).toContain('/trees/HEAD?recursive=1')
+  })
+
+  test('explicit ref is honored', async () => {
+    let capturedUrl = ''
+    const fetch = mockFetch((url) => {
+      capturedUrl = url
+      return { status: 200, body: { tree: [] } }
+    })
+    await fetchRepoTree('github.com', 'o', 'r', 'v1.2.3', fetch)
+    expect(capturedUrl).toContain('/trees/v1.2.3?recursive=1')
+  })
+})

package/src/github-tree.ts

@@ -0,0 +1,111 @@
+/**
+ * Lightweight GitHub Tree API client.
+ *
+ * No SDK, no auth handling — public repos only via built-in `fetch`.
+ * One function: `fetchRepoTree`. Caller passes a fetch implementation
+ * for testing; default is `globalThis.fetch`.
+ *
+ * Endpoint: GET https://api.github.com/repos/{owner}/{repo}/git/trees/{ref}?recursive=1
+ *   200 → tree returned (with optional `truncated: true` for >7MB or 100k entries)
+ *   404 → repo or ref not found
+ *   403 → rate-limited (X-RateLimit-Remaining: 0) or private repo without auth
+ */
+
+export interface TreeEntry {
+  readonly path: string
+  readonly type: 'blob' | 'tree' | 'commit'
+  readonly sha: string
+  readonly size?: number
+}
+
+export interface TreeResponse {
+  readonly status: 'ok' | 'not-found' | 'rate-limited' | 'private' | 'network-error' | 'unsupported-host'
+  readonly entries: ReadonlyArray<TreeEntry>
+  readonly truncated: boolean
+  readonly httpStatus: number
+  readonly message?: string
+}
+
+export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>
+
+const DEFAULT_REF = 'HEAD'
+
+export async function fetchRepoTree(
+  host: string,
+  owner: string,
+  repo: string,
+  ref: string = DEFAULT_REF,
+  fetchImpl: FetchFn = globalThis.fetch,
+): Promise<TreeResponse> {
+  if (host !== 'github.com') {
+    return {
+      status: 'unsupported-host',
+      entries: [],
+      truncated: false,
+      httpStatus: 0,
+      message: `host '${host}' is not supported by fetchRepoTree (only github.com for now)`,
+    }
+  }
+
+  const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`
+
+  let res: Response
+  try {
+    res = await fetchImpl(url, {
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': '@lythos/cold-pool',
+      },
+    })
+  } catch (err) {
+    return {
+      status: 'network-error',
+      entries: [],
+      truncated: false,
+      httpStatus: 0,
+      message: err instanceof Error ? err.message : String(err),
+    }
+  }
+
+  if (res.status === 404) {
+    return {
+      status: 'not-found',
+      entries: [],
+      truncated: false,
+      httpStatus: 404,
+      message: `repo '${owner}/${repo}' or ref '${ref}' not found on github.com`,
+    }
+  }
+
+  if (res.status === 403) {
+    const remaining = res.headers.get('X-RateLimit-Remaining')
+    const isRateLimited = remaining === '0'
+    return {
+      status: isRateLimited ? 'rate-limited' : 'private',
+      entries: [],
+      truncated: false,
+      httpStatus: 403,
+      message: isRateLimited
+        ? 'github.com api rate limit exceeded for unauthenticated requests'
+        : `repo '${owner}/${repo}' is private (or auth required)`,
+    }
+  }
+
+  if (!res.ok) {
+    return {
+      status: 'network-error',
+      entries: [],
+      truncated: false,
+      httpStatus: res.status,
+      message: `unexpected http ${res.status}`,
+    }
+  }
+
+  const body = await res.json() as { tree?: TreeEntry[]; truncated?: boolean }
+  return {
+    status: 'ok',
+    entries: body.tree ?? [],
+    truncated: body.truncated ?? false,
+    httpStatus: 200,
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @lythos/cold-pool — Cold pool service layer.
+ *
+ * Resource layer: `ColdPool`
+ * Plan layer:     `parseLocator`, `buildValidationPlan`, `buildFetchPlan`
+ * Execute layer:  `executeValidationPlan`, `executeFetchPlan`, git IO primitives
+ */
+export type {
+  Locator,
+  ValidationReport,
+  ValidationFindings,
+  SuggestedFix,
+  FetchPlan,
+  FetchResult,
+  FetchIO,
+} from './types.js'
+
+export { parseLocator, formatLocator } from './parse-locator.js'
+export { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool.js'
+
+export type { TreeEntry, TreeResponse, FetchFn } from './github-tree.js'
+export { fetchRepoTree } from './github-tree.js'
+
+export type { InferenceResult } from './infer-skill-path.js'
+export { inferSkillPath } from './infer-skill-path.js'
+
+export type { ValidationPlan, ValidationCheck, ValidationIO } from './validate-plan.js'
+export { buildValidationPlan, executeValidationPlan } from './validate-plan.js'
+
+export type { GitCloneOptions, GitPullResult, GitRootResult } from './git-io.js'
+export { gitClone, gitPull, detectGitRoot } from './git-io.js'
+
+export { buildFetchPlan, executeFetchPlan } from './fetch-plan.js'

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

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test'
+import { inferSkillPath } from './infer-skill-path'
+import type { TreeEntry } from './github-tree'
+
+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', () => {
+    const r = inferSkillPath([blob('SKILL.md'), blob('README.md')])
+    expect(r.candidates).toEqual([''])
+    expect(r.exactMatch).toBeNull()
+  })
+
+  test('monorepo with multiple skills', () => {
+    const r = inferSkillPath([
+      blob('skills/pdf/SKILL.md'),
+      blob('skills/pdf/script.py'),
+      blob('skills/excel/SKILL.md'),
+      tree('skills/empty'),
+    ])
+    expect(r.candidates.sort()).toEqual(['skills/excel', 'skills/pdf'])
+  })
+
+  test('flat repo (root-level skill dirs)', () => {
+    const r = inferSkillPath([
+      blob('skill-creator/SKILL.md'),
+      blob('competitors-analysis/SKILL.md'),
+      blob('README.md'),
+    ])
+    expect(r.candidates.sort()).toEqual(['competitors-analysis', 'skill-creator'])
+  })
+
+  test('nested monorepo (skills/category/skill)', () => {
+    const r = inferSkillPath([
+      blob('skills/engineering/tdd/SKILL.md'),
+      blob('skills/engineering/diagnose/SKILL.md'),
+    ])
+    expect(r.candidates.sort()).toEqual(['skills/engineering/diagnose', 'skills/engineering/tdd'])
+  })
+
+  test('exactMatch reflects expectedSubpath when present', () => {
+    const r = inferSkillPath(
+      [blob('skills/pdf/SKILL.md'), blob('skills/excel/SKILL.md')],
+      'skills/pdf',
+    )
+    expect(r.exactMatch).toBe('skills/pdf')
+  })
+
+  test('exactMatch is null when expectedSubpath is wrong', () => {
+    const r = inferSkillPath(
+      [blob('skills/pdf/SKILL.md')],
+      'pdf', // missing the skills/ prefix
+    )
+    expect(r.exactMatch).toBeNull()
+    expect(r.candidates).toEqual(['skills/pdf'])
+  })
+
+  test('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'),
+    ])
+    expect(r.candidates).toEqual(['skills/x'])
+  })
+
+  test('empty entries → empty candidates', () => {
+    const r = inferSkillPath([])
+    expect(r.candidates).toEqual([])
+    expect(r.exactMatch).toBeNull()
+  })
+})

package/src/infer-skill-path.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure scan of a tree response for SKILL.md candidates.
+ *
+ * Used by validation when a locator's expected skill subpath does not
+ * resolve, or when no skill subpath was given (standalone or ambiguous).
+ */
+import type { TreeEntry } from './github-tree.js'
+
+export interface InferenceResult {
+  /** Directories within the repo that contain a SKILL.md (relative to repo root). Empty string = repo root. */
+  readonly candidates: ReadonlyArray<string>
+  /** When `expectedSubpath` is given: the matching candidate, if exact. */
+  readonly exactMatch: string | null
+}
+
+/**
+ * Scan a flat tree listing for paths ending in `SKILL.md`. Returns the
+ * containing directory paths (relative to repo root). When
+ * `expectedSubpath` is given, also reports whether an exact match exists.
+ */
+export function inferSkillPath(
+  entries: ReadonlyArray<TreeEntry>,
+  expectedSubpath?: string | null,
+): InferenceResult {
+  const candidates: string[] = []
+  for (const e of entries) {
+    if (e.type !== 'blob') continue
+    if (e.path === 'SKILL.md') {
+      candidates.push('')
+      continue
+    }
+    if (e.path.endsWith('/SKILL.md')) {
+      candidates.push(e.path.slice(0, -'/SKILL.md'.length))
+    }
+  }
+
+  if (!expectedSubpath) {
+    return { candidates, exactMatch: null }
+  }
+
+  const exactMatch = candidates.includes(expectedSubpath) ? expectedSubpath : null
+  return { candidates, exactMatch }
+}

package/src/parse-locator.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from 'bun:test'
+import { formatLocator, parseLocator } from './parse-locator'
+
+describe('parseLocator — accepted forms', () => {
+  test('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',
+      host: 'github.com',
+      owner: 'anthropics',
+      repo: 'skills',
+      skill: 'skills/pdf',
+      isLocalhost: false,
+    })
+  })
+
+  test('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)', () => {
+    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)', () => {
+    const loc = parseLocator('github.com/SpillwaveSolutions/design-doc-mermaid')
+    expect(loc).toEqual({
+      raw: 'github.com/SpillwaveSolutions/design-doc-mermaid',
+      host: 'github.com',
+      owner: 'SpillwaveSolutions',
+      repo: 'design-doc-mermaid',
+      skill: null,
+      isLocalhost: false,
+    })
+  })
+
+  test('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)', () => {
+    const loc = parseLocator('localhost/me/my-skill')
+    expect(loc).toEqual({
+      raw: 'localhost/me/my-skill',
+      host: 'localhost',
+      owner: 'me',
+      repo: 'my-skill',
+      skill: null,
+      isLocalhost: true,
+    })
+  })
+
+  test('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', () => {
+    const loc = parseLocator('  github.com/owner/repo  ')
+    expect(loc?.repo).toBe('repo')
+  })
+})
+
+describe('parseLocator — rejected forms (per ADR-20260502012643244 FQ-only)', () => {
+  test('empty string', () => {
+    expect(parseLocator('')).toBeNull()
+    expect(parseLocator('   ')).toBeNull()
+  })
+
+  test('single segment', () => {
+    expect(parseLocator('my-skill')).toBeNull()
+  })
+
+  test('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', () => {
+    expect(parseLocator('foo/bar/baz')).toBeNull()
+  })
+
+  test('host.tld/owner without repo segment', () => {
+    expect(parseLocator('github.com/owner')).toBeNull()
+  })
+
+  test('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',
+      host: 'localhost',
+      owner: 'me',
+      repo: 'skills',
+      skill: 'my-skill',
+      isLocalhost: true,
+    })
+  })
+
+  test('localhost alone (no owner/repo) is rejected', () => {
+    expect(parseLocator('localhost')).toBeNull()
+  })
+
+  test('localhost/<name> (single name, missing repo) is rejected — that was the post-compaction agent invention', () => {
+    expect(parseLocator('localhost/my-skill')).toBeNull()
+  })
+})
+
+describe('formatLocator — round-trips', () => {
+  test.each([
+    'github.com/anthropics/skills/skills/pdf',
+    'github.com/SpillwaveSolutions/design-doc-mermaid',
+    'github.com/mattpocock/skills/skills/engineering/tdd',
+    'localhost/me/my-skill',
+    'localhost/me/skills/inner-skill',
+  ])('round-trip: %s', (raw) => {
+    const parsed = parseLocator(raw)!
+    expect(formatLocator(parsed)).toBe(raw)
+  })
+})

package/src/parse-locator.ts

@@ -0,0 +1,45 @@
+/**
+ * FQ-only locator parser, per ADR-20260502012643244.
+ *
+ * Three accepted forms (everything else returns null):
+ *   - `host.tld/owner/repo[/skill]`        — remote skill
+ *   - `host.tld/owner/repo`                — remote standalone (skill = null)
+ *   - `localhost/owner/repo[/skill]`       — local skill, same shape as remote
+ *
+ * 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".
+ *
+ * Single-name `localhost/<name>` is rejected — that's a post-compaction
+ * agent invention, not the canonical form.
+ */
+import type { Locator } from './types.js'
+
+export function parseLocator(input: string): Locator | null {
+  const trimmed = input.trim()
+  if (!trimmed) return null
+
+  const parts = trimmed.split('/').filter(Boolean)
+  // Need at least host/owner/repo (3 segments) for any FQ form
+  if (parts.length < 3) return null
+
+  // host segment: must be `localhost` (literal) or contain a `.` (host.tld)
+  const isLocalhost = parts[0] === 'localhost'
+  if (!isLocalhost && !parts[0].includes('.')) return null
+
+  return {
+    raw: input,
+    host: parts[0],
+    owner: parts[1],
+    repo: parts[2],
+    skill: parts.length > 3 ? parts.slice(3).join('/') : null,
+    isLocalhost,
+  }
+}
+
+/** Recompose an FQ locator string from a parsed `Locator`. */
+export function formatLocator(locator: Locator): string {
+  const base = `${locator.host}/${locator.owner}/${locator.repo}`
+  return locator.skill ? `${base}/${locator.skill}` : base
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Core types for @lythos/cold-pool.
+ *
+ * Plan-shaped data structures for the intent/plan/execute pattern, plus
+ * the FQ Locator form per ADR-20260502012643244.
+ */
+
+/**
+ * Parsed FQ locator. Per ADR-20260502012643244, three forms only:
+ *   - `host.tld/owner/repo[/skill]` (remote)
+ *   - `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
+ * `isLocalhost` controls is "no remote operations" (no clone, no pull, no fetch).
+ */
+export interface Locator {
+  readonly raw: string
+  readonly host: string
+  readonly owner: string
+  readonly repo: string
+  readonly skill: string | null
+  readonly isLocalhost: boolean
+}
+
+/**
+ * Output of `buildValidationPlan`. Pure data.
+ *
+ * Validation has no separate execute step — the report itself is the plan.
+ * Agents and CLI surfaces consume this directly to render structured
+ * diagnostics (per ADR-20260507014124191).
+ */
+export interface ValidationReport {
+  readonly status: 'valid' | 'invalid' | 'ambiguous'
+  readonly locator: string
+  readonly phase: 'syntax' | 'repo-existence' | 'path-existence' | 'skill-md-existence'
+  readonly findings: ValidationFindings
+  readonly suggestedFixes: ReadonlyArray<SuggestedFix>
+}
+
+export interface ValidationFindings {
+  readonly parseError?: string
+  readonly repoExists?: boolean
+  readonly repoIsPrivate?: boolean
+  readonly skillMdFound?: boolean
+  /** Subdirectories of the cloned repo that contain a SKILL.md, when path-existence fails. */
+  readonly detectedPaths?: ReadonlyArray<string>
+  /** HTTP status from the remote check, if any. */
+  readonly remoteStatus?: number
+}
+
+export interface SuggestedFix {
+  readonly action: 'update-locator' | 'web-search' | 'prompt-user'
+  /** 0..1 — caller decides whether to act unattended. */
+  readonly confidence: number
+  readonly message: string
+  readonly newLocator?: string
+}
+
+/** Per-locator fetch plan. Pure data; no side effects. */
+export interface FetchPlan {
+  readonly locator: Locator
+  readonly cloneUrl: string
+  readonly targetDir: string
+  readonly ref?: string
+  /** When true, executor should skip the clone (idempotent fetch). */
+  readonly alreadyExists: boolean
+}
+
+export interface FetchResult {
+  readonly status: 'cloned' | 'already-present' | 'failed'
+  readonly targetDir: string
+  readonly message?: string
+}
+
+/** Injectable IO for `executeFetchPlan`. Test swaps in mocks. */
+export interface FetchIO {
+  gitClone?: (url: string, dir: string, opts?: { depth?: number; ref?: string }) => void
+  exists?: (path: string) => boolean
+  log?: (msg: string) => void
+}