@lythos/cold-pool 0.9.24

package/src/validate-plan.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from 'bun:test'
+import { buildValidationPlan, executeValidationPlan, type ValidationCheck, type ValidationIO } from './validate-plan'
+import type { FetchFn, TreeEntry } from './github-tree'
+
+function mockFetch(impl: (url: string) => { status: number; body?: unknown; headers?: Record<string, string> }): FetchFn {
+  return async (url) => {
+    const out = impl(url)
+    return new Response(out.body !== undefined ? JSON.stringify(out.body) : null, {
+      status: out.status,
+      headers: out.headers,
+    })
+  }
+}
+
+const treeFor = (paths: string[]): TreeEntry[] =>
+  paths.map((p) => ({ path: p, type: 'blob' as const, sha: 'x' }))
+
+const ioWith = (fetch: FetchFn): ValidationIO => ({ fetch })
+
+describe('buildValidationPlan', () => {
+  test('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', () => {
+    const plan = buildValidationPlan('bad-name')
+    expect(plan.locator).toBeNull()
+  })
+
+  test('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 () => {
+    const plan = buildValidationPlan('bad-name')
+    const report = await executeValidationPlan(plan)
+    expect(report.status).toBe('invalid')
+    expect(report.phase).toBe('syntax')
+    expect(report.findings.parseError).toBeDefined()
+    expect(report.suggestedFixes.length).toBe(1)
+  })
+
+  test('localhost short-circuits — no remote fetch', async () => {
+    const plan = buildValidationPlan('localhost/me/my-skill')
+    let fetched = false
+    const io = ioWith(async () => {
+      fetched = true
+      return new Response(null, { status: 200 })
+    })
+    const report = await executeValidationPlan(plan, io)
+    expect(fetched).toBe(false)
+    expect(report.status).toBe('valid')
+  })
+})
+
+describe('executeValidationPlan — remote phase', () => {
+  test('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')
+    expect(report.phase).toBe('repo-existence')
+    expect(report.findings.repoExists).toBe(false)
+  })
+
+  test('rate-limit → ambiguous', async () => {
+    const plan = buildValidationPlan('github.com/owner/repo')
+    const report = await executeValidationPlan(
+      plan,
+      ioWith(mockFetch(() => ({ status: 403, headers: { 'X-RateLimit-Remaining': '0' } }))),
+    )
+    expect(report.status).toBe('ambiguous')
+    expect(report.phase).toBe('repo-existence')
+  })
+
+  test('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')
+    expect(report.findings.repoIsPrivate).toBe(true)
+  })
+})
+
+describe('executeValidationPlan — path phase', () => {
+  test('standalone (skill=null) with SKILL.md at root → valid', async () => {
+    const plan = buildValidationPlan('github.com/owner/standalone')
+    const fetch = mockFetch(() => ({
+      status: 200,
+      body: { tree: treeFor(['SKILL.md', 'README.md']) },
+    }))
+    const report = await executeValidationPlan(plan, ioWith(fetch))
+    expect(report.status).toBe('valid')
+    expect(report.phase).toBe('skill-md-existence')
+    expect(report.findings.skillMdFound).toBe(true)
+  })
+
+  test('standalone but skills exist in subdirs → invalid + qualified-locator suggestions', async () => {
+    const plan = buildValidationPlan('github.com/owner/repo')
+    const fetch = mockFetch(() => ({
+      status: 200,
+      body: { tree: treeFor(['skills/pdf/SKILL.md', 'skills/excel/SKILL.md']) },
+    }))
+    const report = await executeValidationPlan(plan, ioWith(fetch))
+    expect(report.status).toBe('ambiguous')  // multiple candidates
+    expect(report.suggestedFixes.length).toBe(2)
+    expect(report.suggestedFixes.map((f) => f.newLocator).sort()).toEqual([
+      'github.com/owner/repo/skills/excel',
+      'github.com/owner/repo/skills/pdf',
+    ])
+  })
+
+  test('skill subpath matches → valid', async () => {
+    const plan = buildValidationPlan('github.com/anthropics/skills/skills/pdf')
+    const fetch = mockFetch(() => ({
+      status: 200,
+      body: { tree: treeFor(['skills/pdf/SKILL.md', 'skills/excel/SKILL.md']) },
+    }))
+    const report = await executeValidationPlan(plan, ioWith(fetch))
+    expect(report.status).toBe('valid')
+  })
+
+  test('skill subpath wrong → invalid + corrected suggestion', async () => {
+    const plan = buildValidationPlan('github.com/anthropics/skills/pdf')  // missing skills/ prefix
+    const fetch = mockFetch(() => ({
+      status: 200,
+      body: { tree: treeFor(['skills/pdf/SKILL.md']) },
+    }))
+    const report = await executeValidationPlan(plan, ioWith(fetch))
+    expect(report.status).toBe('invalid')
+    expect(report.phase).toBe('path-existence')
+    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 () => {
+    const plan = buildValidationPlan('github.com/owner/random-repo')
+    const fetch = mockFetch(() => ({
+      status: 200,
+      body: { tree: treeFor(['README.md', 'src/index.ts']) },
+    }))
+    const report = await executeValidationPlan(plan, ioWith(fetch))
+    expect(report.status).toBe('invalid')
+    expect(report.suggestedFixes.some((f) => f.action === 'web-search')).toBe(true)
+  })
+})
+
+describe('executeValidationPlan — scoped checks', () => {
+  test('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 () => {
+      fetched = true
+      return new Response(null, { status: 200 })
+    })
+    const report = await executeValidationPlan(plan, io)
+    expect(fetched).toBe(false)
+    expect(report.status).toBe('valid')
+  })
+})

package/src/validate-plan.ts

@@ -0,0 +1,259 @@
+/**
+ * Validation plan + executor.
+ *
+ * `buildValidationPlan` is pure — it parses the input and chooses which
+ * checks to run. `executeValidationPlan` performs the side-effecting
+ * remote tree fetch via injected IO and produces a `ValidationReport`.
+ *
+ * Per ADR-20260507014124191, the report is structured data so agents
+ * can recover from validation failure (suggested fixes, detected paths)
+ * instead of parsing strings.
+ */
+import type { Locator, SuggestedFix, ValidationFindings, ValidationReport } from './types.js'
+import { parseLocator, formatLocator } from './parse-locator.js'
+import type { FetchFn, TreeResponse } from './github-tree.js'
+import { fetchRepoTree } from './github-tree.js'
+import { inferSkillPath } from './infer-skill-path.js'
+
+export type ValidationCheck = 'syntax' | 'remote' | 'path'
+
+export interface ValidationPlan {
+  readonly rawInput: string
+  readonly locator: Locator | null
+  readonly checks: ReadonlyArray<ValidationCheck>
+  /** Optional git ref to validate against (default: HEAD). */
+  readonly ref?: string
+}
+
+export interface ValidationIO {
+  fetch?: FetchFn
+  log?: (msg: string) => void
+}
+
+const DEFAULT_CHECKS: ValidationCheck[] = ['syntax', 'remote', 'path']
+
+export function buildValidationPlan(
+  rawInput: string,
+  opts?: { checks?: ReadonlyArray<ValidationCheck>; ref?: string },
+): ValidationPlan {
+  return {
+    rawInput,
+    locator: parseLocator(rawInput),
+    checks: opts?.checks ?? DEFAULT_CHECKS,
+    ref: opts?.ref,
+  }
+}
+
+export async function executeValidationPlan(
+  plan: ValidationPlan,
+  io?: ValidationIO,
+): Promise<ValidationReport> {
+  const fixes: SuggestedFix[] = []
+
+  // ── 1. Syntax phase ───────────────────────────────────────────────
+  if (!plan.locator) {
+    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.',
+    })
+    return {
+      status: 'invalid',
+      locator: plan.rawInput,
+      phase: 'syntax',
+      findings: { parseError: 'parseLocator returned null' },
+      suggestedFixes: fixes,
+    }
+  }
+
+  if (!plan.checks.includes('syntax')) {
+    // Skipped; treat as if we only got past parsing but not asked to remote-check.
+  }
+
+  // ── 2. Localhost early-return ─────────────────────────────────────
+  if (plan.locator.isLocalhost) {
+    return {
+      status: 'valid',
+      locator: plan.rawInput,
+      phase: 'syntax',
+      findings: {},
+      suggestedFixes: [],
+    }
+  }
+
+  // ── 3. Remote phase (and 4. Path phase) ───────────────────────────
+  if (!plan.checks.includes('remote') && !plan.checks.includes('path')) {
+    return {
+      status: 'valid',
+      locator: plan.rawInput,
+      phase: 'syntax',
+      findings: {},
+      suggestedFixes: [],
+    }
+  }
+
+  const tree: TreeResponse = await fetchRepoTree(
+    plan.locator.host,
+    plan.locator.owner!,
+    plan.locator.repo!,
+    plan.ref,
+    io?.fetch,
+  )
+
+  io?.log?.(`tree fetch: ${tree.status} (http ${tree.httpStatus})`)
+
+  if (tree.status === 'not-found') {
+    fixes.push({
+      action: 'update-locator',
+      confidence: 0.7,
+      message: `repo not found on ${plan.locator.host}. Verify owner/repo spelling.`,
+    })
+    return {
+      status: 'invalid',
+      locator: plan.rawInput,
+      phase: 'repo-existence',
+      findings: { repoExists: false, remoteStatus: 404 },
+      suggestedFixes: fixes,
+    }
+  }
+
+  if (tree.status === 'rate-limited' || tree.status === 'network-error' || tree.status === 'unsupported-host') {
+    // Cannot determine — return ambiguous, agent decides whether to clone-and-test
+    fixes.push({
+      action: 'prompt-user',
+      confidence: 0.3,
+      message: tree.message ?? 'remote check failed; locator may still be valid',
+    })
+    return {
+      status: 'ambiguous',
+      locator: plan.rawInput,
+      phase: 'repo-existence',
+      findings: { remoteStatus: tree.httpStatus },
+      suggestedFixes: fixes,
+    }
+  }
+
+  if (tree.status === 'private') {
+    fixes.push({
+      action: 'prompt-user',
+      confidence: 0.6,
+      message: `repo appears private; auth is not implemented in cold-pool. Clone manually if access is granted, then deck add will reuse the cold pool entry.`,
+    })
+    return {
+      status: 'ambiguous',
+      locator: plan.rawInput,
+      phase: 'repo-existence',
+      findings: { repoExists: true, repoIsPrivate: true, remoteStatus: 403 },
+      suggestedFixes: fixes,
+    }
+  }
+
+  // tree.status === 'ok'
+  if (!plan.checks.includes('path')) {
+    return {
+      status: 'valid',
+      locator: plan.rawInput,
+      phase: 'repo-existence',
+      findings: { repoExists: true, remoteStatus: 200 },
+      suggestedFixes: [],
+    }
+  }
+
+  // 4. Path phase: scan tree for SKILL.md
+  const inference = inferSkillPath(tree.entries, plan.locator.skill)
+
+  const findingsBase: ValidationFindings = {
+    repoExists: true,
+    remoteStatus: 200,
+    skillMdFound: inference.exactMatch !== null,
+    detectedPaths: inference.candidates,
+  }
+
+  if (plan.locator.skill === null) {
+    // standalone — expect SKILL.md at repo root
+    if (inference.candidates.includes('')) {
+      return {
+        status: 'valid',
+        locator: plan.rawInput,
+        phase: 'skill-md-existence',
+        findings: { ...findingsBase, skillMdFound: true },
+        suggestedFixes: [],
+      }
+    }
+    if (inference.candidates.length === 0) {
+      fixes.push({
+        action: 'web-search',
+        confidence: 0.4,
+        message: 'no SKILL.md found in this repo; the locator may not point to a skill repo',
+      })
+      return {
+        status: 'invalid',
+        locator: plan.rawInput,
+        phase: 'skill-md-existence',
+        findings: findingsBase,
+        suggestedFixes: fixes,
+      }
+    }
+    // standalone but skills exist in subdirs → suggest qualifying
+    const status = inference.candidates.length === 1 ? 'invalid' : 'ambiguous'
+    for (const candidate of inference.candidates) {
+      const newLocator = formatLocator({
+        ...plan.locator,
+        skill: candidate,
+      })
+      fixes.push({
+        action: 'update-locator',
+        confidence: inference.candidates.length === 1 ? 0.8 : 0.5,
+        message: `repo has skill at '${candidate}/'; qualify the locator`,
+        newLocator,
+      })
+    }
+    return {
+      status,
+      locator: plan.rawInput,
+      phase: 'skill-md-existence',
+      findings: findingsBase,
+      suggestedFixes: fixes,
+    }
+  }
+
+  // skill subpath given
+  if (inference.exactMatch !== null) {
+    return {
+      status: 'valid',
+      locator: plan.rawInput,
+      phase: 'skill-md-existence',
+      findings: findingsBase,
+      suggestedFixes: [],
+    }
+  }
+
+  // suggest candidates
+  for (const candidate of inference.candidates) {
+    const newLocator = formatLocator({
+      ...plan.locator,
+      skill: candidate || null,
+    })
+    fixes.push({
+      action: 'update-locator',
+      confidence: candidate.endsWith('/' + plan.locator.skill) || candidate === plan.locator.skill ? 0.9 : 0.4,
+      message: `SKILL.md found at '${candidate || '(repo root)'}'`,
+      newLocator,
+    })
+  }
+  if (inference.candidates.length === 0) {
+    fixes.push({
+      action: 'web-search',
+      confidence: 0.4,
+      message: 'no SKILL.md anywhere in this repo; the locator may not point to a skill repo',
+    })
+  }
+
+  return {
+    status: 'invalid',
+    locator: plan.rawInput,
+    phase: 'path-existence',
+    findings: findingsBase,
+    suggestedFixes: fixes,
+  }
+}