@batonfx/skills 0.3.6 → 0.4.0

package/src/skill-loader.ts

@@ -1,5 +1,6 @@
 import { Effect, FileSystem, Layer, Path, PlatformError, Stream } from "effect"
 import { SkillSource } from "@batonfx/core"
+import { parseDocument, parseFrontmatter, splitDocument } from "./skill-document"
 
 /** @experimental Filesystem skill-loader options. */
 export interface LoadOptions {
@@ -13,171 +14,12 @@ const DEFAULT_ROOTS = [".agents/skills", ".claude/skills", ".pi/skills"] as cons
 
 const decoder = new TextDecoder()
 
-interface ParsedDocument {
-  readonly frontmatter: SkillSource.Frontmatter
-  readonly body: string
-}
-
-interface ParsedHeader {
-  name?: string
-  description?: string
-  whenToUse?: string
-  allowedTools?: ReadonlyArray<string>
-  disableModelInvocation?: boolean
-  userInvocable?: boolean
-  contextFork?: boolean
-  agent?: string
-  model?: string
-  paths?: ReadonlyArray<string>
-}
-
 const sourceError = (source: string, message: string, cause?: unknown): SkillSource.SkillSourceError =>
   new SkillSource.SkillSourceError({ source, message, ...(cause === undefined ? {} : { cause }) })
 
 const mapPlatformError = (source: string, error: PlatformError.PlatformError): SkillSource.SkillSourceError =>
   sourceError(source, error.message, error)
 
-const normalizeKey = (key: string): string => key.replace(/[-_]/g, "").toLowerCase()
-
-const stripQuotes = (value: string): string => {
-  const trimmed = value.trim()
-  return (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))
-    ? trimmed.slice(1, -1)
-    : trimmed
-}
-
-const parseInlineArray = (value: string): ReadonlyArray<string> => {
-  const trimmed = value.trim()
-  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return []
-  const inner = trimmed.slice(1, -1).trim()
-  return inner.length === 0 ? [] : inner.split(",").map((item) => stripQuotes(item).trim())
-}
-
-const parseBoolean = (value: string): boolean | undefined => {
-  const lowered = value.trim().toLowerCase()
-  if (lowered === "true") return true
-  if (lowered === "false") return false
-  return undefined
-}
-
-const setValue = (target: Partial<ParsedHeader>, key: string, value: string | boolean | ReadonlyArray<string>) => {
-  switch (normalizeKey(key)) {
-    case "name":
-      if (typeof value === "string") target.name = value
-      break
-    case "description":
-      if (typeof value === "string") target.description = value
-      break
-    case "whentouse":
-      if (typeof value === "string") target.whenToUse = value
-      break
-    case "allowedtools":
-      if (Array.isArray(value)) target.allowedTools = value
-      break
-    case "disablemodelinvocation":
-      if (typeof value === "boolean") target.disableModelInvocation = value
-      break
-    case "userinvocable":
-      if (typeof value === "boolean") target.userInvocable = value
-      break
-    case "contextfork":
-      if (typeof value === "boolean") target.contextFork = value
-      break
-    case "agent":
-      if (typeof value === "string") target.agent = value
-      break
-    case "model":
-      if (typeof value === "string") target.model = value
-      break
-    case "paths":
-      if (Array.isArray(value)) target.paths = value
-      break
-  }
-}
-
-const parseHeader = (source: string, block: string): Effect.Effect<ParsedHeader, SkillSource.SkillSourceError> =>
-  Effect.sync(() => {
-    const parsed: Partial<ParsedHeader> = {}
-    const lines = block.split("\n")
-    for (let index = 0; index < lines.length; index += 1) {
-      const line = lines[index]?.trimEnd() ?? ""
-      if (line.trim().length === 0) continue
-      const separator = line.indexOf(":")
-      if (separator === -1) continue
-      const key = line.slice(0, separator).trim()
-      const raw = line.slice(separator + 1).trim()
-      if (raw.length === 0) {
-        const values: Array<string> = []
-        while ((lines[index + 1]?.trimStart().startsWith("- ") ?? false) === true) {
-          index += 1
-          values.push(stripQuotes((lines[index] ?? "").trimStart().slice(2)))
-        }
-        setValue(parsed, key, values)
-      } else if (raw.startsWith("[") && raw.endsWith("]")) {
-        setValue(parsed, key, parseInlineArray(raw))
-      } else {
-        setValue(parsed, key, parseBoolean(raw) ?? stripQuotes(raw))
-      }
-    }
-    return parsed
-  }).pipe(Effect.catchCause((cause) => Effect.fail(sourceError(source, "Invalid SKILL.md frontmatter", cause))))
-
-const splitDocument = (
-  source: string,
-  content: string,
-): Effect.Effect<readonly [string, string], SkillSource.SkillSourceError> =>
-  Effect.gen(function* () {
-    const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n")
-    const lines = normalized.split("\n")
-    if (lines[0] !== "---") {
-      return yield* Effect.fail(sourceError(source, "Invalid SKILL.md document: missing opening frontmatter fence"))
-    }
-    const close = lines.findIndex((line, index) => index > 0 && line === "---")
-    if (close === -1) {
-      return yield* Effect.fail(sourceError(source, "Invalid SKILL.md document: missing closing frontmatter fence"))
-    }
-    return [lines.slice(1, close).join("\n"), lines.slice(close + 1).join("\n")] as const
-  })
-
-const namespacedName = (path: Path.Path, relativeFile: string, explicitName: string | undefined): string => {
-  const directory = path.dirname(relativeFile)
-  const segments = directory === "." ? [] : directory.split("/").filter((part) => part.length > 0)
-  const directoryName = segments.at(-1) ?? path.basename(path.dirname(relativeFile))
-  const baseName = explicitName ?? directoryName
-  const namespace = segments.slice(0, -1).join(":")
-  return baseName.includes(":") || namespace.length === 0 ? baseName : `${namespace}:${baseName}`
-}
-
-const parseDocument = (
-  source: string,
-  content: string,
-  name: string,
-): Effect.Effect<ParsedDocument, SkillSource.SkillSourceError> =>
-  Effect.gen(function* () {
-    const [header, body] = yield* splitDocument(source, content)
-    const parsed = yield* parseHeader(source, header)
-    if (parsed.description === undefined || parsed.description.length === 0) {
-      return yield* Effect.fail(sourceError(source, "SKILL.md frontmatter requires description"))
-    }
-    return {
-      body,
-      frontmatter: {
-        name,
-        description: parsed.description,
-        ...(parsed.whenToUse === undefined ? {} : { whenToUse: parsed.whenToUse }),
-        ...(parsed.allowedTools === undefined ? {} : { allowedTools: parsed.allowedTools }),
-        ...(parsed.disableModelInvocation === undefined
-          ? {}
-          : { disableModelInvocation: parsed.disableModelInvocation }),
-        ...(parsed.userInvocable === undefined ? {} : { userInvocable: parsed.userInvocable }),
-        ...(parsed.contextFork === undefined ? {} : { contextFork: parsed.contextFork }),
-        ...(parsed.agent === undefined ? {} : { agent: parsed.agent }),
-        ...(parsed.model === undefined ? {} : { model: parsed.model }),
-        ...(parsed.paths === undefined ? {} : { paths: parsed.paths }),
-      },
-    }
-  })
-
 const readHeader = (
   fs: FileSystem.FileSystem,
   source: string,
@@ -202,29 +44,16 @@ const loadSkill = (
   Effect.gen(function* () {
     const header = yield* readHeader(fs, file, frontmatterMaxBytes)
     const [headerBlock] = yield* splitDocument(file, header)
-    const parsed = yield* parseHeader(file, headerBlock)
-    const name = namespacedName(path, relativeFile, parsed.name)
-    if (parsed.description === undefined || parsed.description.length === 0) {
-      return yield* Effect.fail(sourceError(file, "SKILL.md frontmatter requires description"))
-    }
-    const frontmatter: SkillSource.Frontmatter = {
-      name,
-      description: parsed.description,
-      ...(parsed.whenToUse === undefined ? {} : { whenToUse: parsed.whenToUse }),
-      ...(parsed.allowedTools === undefined ? {} : { allowedTools: parsed.allowedTools }),
-      ...(parsed.disableModelInvocation === undefined ? {} : { disableModelInvocation: parsed.disableModelInvocation }),
-      ...(parsed.userInvocable === undefined ? {} : { userInvocable: parsed.userInvocable }),
-      ...(parsed.contextFork === undefined ? {} : { contextFork: parsed.contextFork }),
-      ...(parsed.agent === undefined ? {} : { agent: parsed.agent }),
-      ...(parsed.model === undefined ? {} : { model: parsed.model }),
-      ...(parsed.paths === undefined ? {} : { paths: parsed.paths }),
-    }
+    const directoryName = path.basename(path.dirname(relativeFile))
+    const frontmatter = yield* parseFrontmatter(file, headerBlock, directoryName)
     return {
       frontmatter,
       listing: SkillSource.makeListing(frontmatter, descriptionCap),
       body: fs.readFileString(file).pipe(
         Effect.mapError((error) => mapPlatformError(file, error)),
-        Effect.flatMap((content) => parseDocument(file, content, name).pipe(Effect.map((document) => document.body))),
+        Effect.flatMap((content) =>
+          parseDocument(file, content, directoryName).pipe(Effect.map((document) => document.body)),
+        ),
       ),
       tools: [],
     }
@@ -254,29 +83,30 @@ const discoverRoot = (
     return skills
   })
 
-/** @experimental Build a SkillSource from filesystem roots. */
+/** @experimental Build a composable SkillSource from filesystem roots. */
+export const make = (options: LoadOptions = {}): SkillSource.Source<FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const cwd = options.cwd === undefined ? "." : path.resolve(options.cwd)
+    const roots = options.roots ?? DEFAULT_ROOTS
+    const descriptionCap = options.descriptionCap ?? SkillSource.DESCRIPTION_CAP
+    const frontmatterMaxBytes = options.frontmatterMaxBytes ?? 64 * 1024
+    const byName = new Map<string, SkillSource.Skill>()
+    for (const root of roots) {
+      for (const skill of yield* discoverRoot(fs, path, cwd, root, descriptionCap, frontmatterMaxBytes)) {
+        byName.set(skill.frontmatter.name, skill)
+      }
+    }
+    const skills = [...byName.values()]
+    return {
+      all: Effect.succeed(skills),
+      get: (name) => Effect.succeed(byName.get(name)),
+    }
+  })
+
+/** @experimental Build a SkillSource layer from filesystem roots. */
 export const layer = (
   options: LoadOptions = {},
 ): Layer.Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, FileSystem.FileSystem | Path.Path> =>
-  Layer.effect(
-    SkillSource.SkillSource,
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem
-      const path = yield* Path.Path
-      const cwd = options.cwd === undefined ? "." : path.resolve(options.cwd)
-      const roots = options.roots ?? DEFAULT_ROOTS
-      const descriptionCap = options.descriptionCap ?? SkillSource.DESCRIPTION_CAP
-      const frontmatterMaxBytes = options.frontmatterMaxBytes ?? 64 * 1024
-      const byName = new Map<string, SkillSource.Skill>()
-      for (const root of roots) {
-        for (const skill of yield* discoverRoot(fs, path, cwd, root, descriptionCap, frontmatterMaxBytes)) {
-          byName.set(skill.frontmatter.name, skill)
-        }
-      }
-      const skills = [...byName.values()]
-      return SkillSource.SkillSource.of({
-        all: Effect.succeed(skills),
-        get: (name) => Effect.succeed(byName.get(name)),
-      })
-    }),
-  )
+  Layer.effect(SkillSource.SkillSource, make(options).pipe(Effect.map(SkillSource.SkillSource.of)))

package/test/hosted-catalog.test.ts

@@ -0,0 +1,398 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Crypto, Effect, Encoding, Layer } from "effect"
+import { HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { SkillSource } from "@batonfx/core"
+import { GitHubCatalog, HttpCatalog, S3Catalog } from "../src/index"
+
+const digestBytes = new Uint8Array(32).fill(1)
+const digest = Encoding.encodeHex(digestBytes)
+
+const cryptoLayer = (bytes: Uint8Array = digestBytes) =>
+  Layer.succeed(
+    Crypto.Crypto,
+    Crypto.make({
+      randomBytes: (size) => new Uint8Array(size),
+      digest: () => Effect.succeed(bytes),
+    }),
+  )
+
+const httpLayer = (
+  responses: Readonly<
+    Record<string, { readonly body: string | Uint8Array | ReadableStream<Uint8Array>; readonly status?: number }>
+  >,
+  requests: Array<{ readonly url: string; readonly accept: string | undefined }>,
+) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request, url) => {
+      const target = url.toString()
+      requests.push({ url: target, accept: request.headers.accept })
+      const response = responses[target]
+      return Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          new Response(response?.body ?? "missing", {
+            status: response?.status ?? (response === undefined ? 404 : 200),
+          }),
+        ),
+      )
+    }),
+  )
+
+const document = `---
+name: remote
+description: Remote review skill
+allowed-tools: read grep
+---
+# Remote body
+Review carefully.
+`
+
+const manifest = (skillPath: string = "remote/SKILL.md", sha256: string = digest) =>
+  JSON.stringify({
+    version: 1,
+    skills: [
+      {
+        name: "remote",
+        description: "Remote review skill",
+        allowedTools: ["read", "grep"],
+        skillPath,
+        sha256,
+      },
+    ],
+  })
+
+describe("hosted skill catalogs", () => {
+  it.effect("loads HTTP metadata once and keeps verified SKILL.md bodies lazy", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const manifestUrl = "https://skills.example/catalog/skills.json"
+    const bodyUrl = "https://skills.example/catalog/remote/SKILL.md"
+    return Effect.gen(function* () {
+      const source = yield* HttpCatalog.make({ manifestUrl, source: "company-skills" })
+      const all = yield* source.all
+
+      expect(all.map((skill) => skill.frontmatter.name)).toEqual(["remote"])
+      expect(requests.map((request) => request.url)).toEqual([manifestUrl])
+
+      const body = yield* all[0]!.body
+
+      expect(body).toContain("# Remote body")
+      expect(requests.map((request) => request.url)).toEqual([manifestUrl, bodyUrl])
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer({ [manifestUrl]: { body: manifest() }, [bodyUrl]: { body: document } }, requests),
+        ),
+      ),
+    )
+  })
+
+  it.effect("rejects unsafe hosted paths during source construction", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const manifestUrl = "https://skills.example/catalog/skills.json"
+    return Effect.gen(function* () {
+      const failure = yield* Effect.flip(HttpCatalog.make({ manifestUrl, source: "unsafe-catalog" }))
+
+      expect(failure._tag).toBe("@batonfx/core/SkillSourceError")
+      expect(failure.source).toBe("unsafe-catalog")
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(cryptoLayer(), httpLayer({ [manifestUrl]: { body: manifest("../escape/SKILL.md") } }, requests)),
+      ),
+    )
+  })
+
+  it.effect("fails digest mismatches on activation and allows a later retry", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const manifestUrl = "https://skills.example/catalog/skills.json"
+    const bodyUrl = "https://skills.example/catalog/remote/SKILL.md"
+    return Effect.gen(function* () {
+      const source = yield* HttpCatalog.make({ manifestUrl, source: "retry-catalog" })
+      const skill = yield* source.get("remote")
+      const first = yield* Effect.exit(skill!.body)
+      const second = yield* Effect.exit(skill!.body)
+
+      expect(first._tag).toBe("Failure")
+      expect(second._tag).toBe("Failure")
+      expect(requests.filter((request) => request.url === bodyUrl)).toHaveLength(2)
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(new Uint8Array(32).fill(2)),
+          httpLayer({ [manifestUrl]: { body: manifest() }, [bodyUrl]: { body: document } }, requests),
+        ),
+      ),
+    )
+  })
+
+  it.effect("rejects frontmatter drift after a verified body fetch", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const manifestUrl = "https://skills.example/catalog/skills.json"
+    const bodyUrl = "https://skills.example/catalog/remote/SKILL.md"
+    const drifted = document.replace("Remote review skill", "Changed after publication")
+    return Effect.gen(function* () {
+      const source = yield* HttpCatalog.make({ manifestUrl, source: "drift-catalog" })
+      const skill = yield* source.get("remote")
+      const failure = yield* Effect.flip(skill!.body)
+
+      expect(failure._tag).toBe("@batonfx/core/SkillSourceError")
+      expect(failure.message).toContain("Frontmatter mismatch")
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer({ [manifestUrl]: { body: manifest() }, [bodyUrl]: { body: drifted } }, requests),
+        ),
+      ),
+    )
+  })
+
+  it.effect("rejects duplicate names and bounded manifest overflows", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const duplicateUrl = "https://skills.example/duplicate.json"
+    const limitedUrl = "https://skills.example/limited.json"
+    const duplicate = JSON.stringify({
+      version: 1,
+      skills: [...JSON.parse(manifest()).skills, ...JSON.parse(manifest()).skills],
+    })
+    return Effect.gen(function* () {
+      const duplicateFailure = yield* Effect.flip(HttpCatalog.make({ manifestUrl: duplicateUrl }))
+      const limitedFailure = yield* Effect.flip(HttpCatalog.make({ manifestUrl: limitedUrl, manifestMaxBytes: 1 }))
+
+      expect(duplicateFailure.message).toContain("Duplicate hosted skill name")
+      expect(limitedFailure.message).toContain("exceeds 1 bytes")
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer({ [duplicateUrl]: { body: duplicate }, [limitedUrl]: { body: manifest() } }, requests),
+        ),
+      ),
+    )
+  })
+
+  it.effect("maps non-success HTTP responses to safe source errors", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const manifestUrl = "https://user:password@skills.example/private/skills.json?signature=secret#fragment"
+    return Effect.gen(function* () {
+      const failure = yield* Effect.flip(HttpCatalog.make({ manifestUrl }))
+
+      expect(failure.source).toBe("https://skills.example/private/skills.json")
+      expect(failure.source).not.toContain("secret")
+      expect(failure.source).not.toContain("password")
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(cryptoLayer(), httpLayer({ [manifestUrl]: { body: "forbidden", status: 403 } }, requests)),
+      ),
+    )
+  })
+
+  it.effect("constructs S3 and immutable GitHub catalog endpoints", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const commit = "a".repeat(40)
+    const s3Manifest = "https://company-skills.s3.us-west-2.amazonaws.com/support/skills.json"
+    const s3Body = "https://company-skills.s3.us-west-2.amazonaws.com/support/remote/SKILL.md"
+    const githubManifest = `https://api.github.com/repos/acme/agent-skills/contents/skills/skills.json?ref=${commit}`
+    const githubBody = `https://api.github.com/repos/acme/agent-skills/contents/skills/remote/SKILL.md?ref=${commit}`
+    return Effect.gen(function* () {
+      const s3 = yield* S3Catalog.make({ bucket: "company-skills", region: "us-west-2", prefix: "support" })
+      const github = yield* GitHubCatalog.make({
+        owner: "acme",
+        repo: "agent-skills",
+        ref: commit,
+        root: "skills",
+      })
+
+      yield* (yield* s3.get("remote"))!.body
+      yield* (yield* github.get("remote"))!.body
+
+      expect(requests.map((request) => request.url)).toEqual([s3Manifest, githubManifest, s3Body, githubBody])
+      expect(requests.filter((request) => request.url.startsWith("https://api.github.com"))).toSatisfy(
+        (items: ReadonlyArray<{ readonly accept: string | undefined }>) =>
+          items.every((request) => request.accept === "application/vnd.github.raw+json"),
+      )
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer(
+            {
+              [s3Manifest]: { body: manifest() },
+              [s3Body]: { body: document },
+              [githubManifest]: { body: manifest() },
+              [githubBody]: { body: document },
+            },
+            requests,
+          ),
+        ),
+      ),
+    )
+  })
+
+  it.effect("requires GitHub refs to be immutable commit ids", () =>
+    Effect.gen(function* () {
+      const failure = yield* Effect.flip(
+        GitHubCatalog.make({ owner: "acme", repo: "agent-skills", ref: "main", root: "skills" }),
+      )
+      expect(failure._tag).toBe("@batonfx/core/SkillSourceError")
+    }).pipe(Effect.provide(Layer.mergeAll(cryptoLayer(), httpLayer({}, [])))),
+  )
+
+  it.effect("bounds raw streamed bytes before buffering and rejects invalid UTF-8", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const limitedUrl = "https://skills.example/streamed.json"
+    const invalidUrl = "https://skills.example/invalid.json"
+    let pulls = 0
+    const streamed = new ReadableStream<Uint8Array>(
+      {
+        pull(controller) {
+          pulls += 1
+          controller.enqueue(new Uint8Array([123, 34, 120]))
+          if (pulls >= 3) controller.close()
+        },
+      },
+      { highWaterMark: 0 },
+    )
+    return Effect.gen(function* () {
+      const limited = yield* Effect.flip(HttpCatalog.make({ manifestUrl: limitedUrl, manifestMaxBytes: 4 }))
+      const invalid = yield* Effect.flip(HttpCatalog.make({ manifestUrl: invalidUrl }))
+
+      expect(limited.message).toContain("exceeds 4 bytes")
+      expect(pulls).toBeLessThan(3)
+      expect(invalid.message).toContain("UTF-8")
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer(
+            {
+              [limitedUrl]: { body: streamed },
+              [invalidUrl]: { body: new Uint8Array([0xff]) },
+            },
+            requests,
+          ),
+        ),
+      ),
+    )
+  })
+
+  it.effect("hashes exact body bytes and does not inherit tools from record prototypes", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const manifestUrl = "https://skills.example/catalog/skills.json"
+    const bodyUrl = "https://skills.example/catalog/constructor/SKILL.md"
+    const raw = new TextEncoder().encode(`---\nname: constructor\ndescription: Safe own-property lookup\n---\nbody`)
+    let hashed: Uint8Array | undefined
+    const manifestBody = JSON.stringify({
+      version: 1,
+      skills: [
+        {
+          name: "constructor",
+          description: "Safe own-property lookup",
+          skillPath: "constructor/SKILL.md",
+          sha256: digest,
+        },
+      ],
+    })
+    const recordingCrypto = Layer.succeed(
+      Crypto.Crypto,
+      Crypto.make({
+        randomBytes: (size) => new Uint8Array(size),
+        digest: (_algorithm, bytes) => {
+          hashed = bytes
+          return Effect.succeed(digestBytes)
+        },
+      }),
+    )
+    return Effect.gen(function* () {
+      const source = yield* HttpCatalog.make({ manifestUrl, toolsBySkill: {} })
+      const skill = yield* source.get("constructor")
+      yield* skill!.body
+
+      expect([...hashed!]).toEqual([...raw])
+      expect(skill!.tools).toEqual([])
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          recordingCrypto,
+          httpLayer({ [manifestUrl]: { body: manifestBody }, [bodyUrl]: { body: raw } }, requests),
+        ),
+      ),
+    )
+  })
+
+  it.effect("rejects unsafe provider components and encoded hosted paths", () =>
+    Effect.gen(function* () {
+      const commit = "a".repeat(40)
+      const encodedPathUrl = "https://skills.example/catalog.json"
+      const failures = yield* Effect.all([
+        Effect.flip(GitHubCatalog.make({ owner: "..", repo: "skills", ref: commit })),
+        Effect.flip(GitHubCatalog.make({ owner: "acme", repo: "..", ref: commit })),
+        Effect.flip(
+          GitHubCatalog.make({
+            owner: "acme",
+            repo: "skills",
+            ref: commit,
+            apiBaseUrl: "https://user:secret@git.example/api?token=secret",
+          }),
+        ),
+        Effect.flip(S3Catalog.make({ bucket: "company.skills", region: "us-west-2" })),
+        Effect.flip(S3Catalog.make({ bucket: "192.168.1.1", region: "us-west-2" })),
+        Effect.flip(HttpCatalog.make({ manifestUrl: encodedPathUrl })),
+      ])
+      expect(failures).toHaveLength(6)
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer(
+            {
+              "https://skills.example/catalog.json": {
+                body: manifest("remote%2fescape/SKILL.md"),
+              },
+            },
+            [],
+          ),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("composes public filesystem-independent adapters with later sources winning", () => {
+    const requests: Array<{ readonly url: string; readonly accept: string | undefined }> = []
+    const httpUrl = "https://skills.example/catalog.json"
+    const s3Url = "https://company-skills.s3.us-west-2.amazonaws.com/skills.json"
+    const secondManifest = JSON.stringify({
+      version: 1,
+      skills: [
+        {
+          name: "remote",
+          description: "Later source wins",
+          skillPath: "remote/SKILL.md",
+          sha256: digest,
+        },
+      ],
+    })
+    return Effect.gen(function* () {
+      const source = yield* SkillSource.SkillSource
+      const all = yield* source.all
+      const remote = yield* source.get("remote")
+
+      expect(all).toHaveLength(1)
+      expect(remote?.frontmatter.description).toBe("Later source wins")
+    }).pipe(
+      Effect.provide(
+        SkillSource.layer([
+          HttpCatalog.make({ manifestUrl: httpUrl }),
+          S3Catalog.make({ bucket: "company-skills", region: "us-west-2" }),
+        ]),
+      ),
+      Effect.provide(
+        Layer.mergeAll(
+          cryptoLayer(),
+          httpLayer({ [httpUrl]: { body: manifest() }, [s3Url]: { body: secondManifest } }, requests),
+        ),
+      ),
+    )
+  })
+})