opencode-effect-enforcer 0.2.0

package/src/agent-policy.ts

@@ -0,0 +1,22 @@
+const REQUEST_KEY = "opencode-effect-enforcer"
+
+interface AgentPolicyTarget {
+  readonly request: {
+    readonly body: Record<string, unknown>
+  }
+  readonly permissions: Array<{
+    readonly action: string
+    readonly resource: string
+    readonly effect: "allow" | "ask" | "deny"
+  }>
+}
+
+/** Consume an agent's Effect Enforcer setting and apply its skill opt-out. */
+export const consumeAgentOptOut = (agent: AgentPolicyTarget): boolean => {
+  const disabled = agent.request.body[REQUEST_KEY] === false
+  delete agent.request.body[REQUEST_KEY]
+  if (!disabled) return false
+
+  agent.permissions.push({ action: "skill", resource: "effect-*", effect: "deny" })
+  return true
+}

package/src/enforcer.ts

@@ -0,0 +1,104 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+import { buildPatternFeedback } from "./guidance.ts"
+import { matchesPattern } from "./pattern-matcher.ts"
+import { Pattern } from "./pattern.ts"
+import { actualProjection, type FileSnapshot, snapshotFile } from "./write-projection.ts"
+
+interface PendingWrite {
+  readonly files: ReadonlyArray<FileSnapshot>
+  readonly fullFile: boolean
+}
+
+const property = (value: unknown, key: string): unknown =>
+  typeof value === "object" && value !== null ? Reflect.get(value, key) : undefined
+
+const stringProperty = (value: unknown, key: string): string | undefined => {
+  const current = property(value, key)
+  return typeof current === "string" ? current : undefined
+}
+
+const patchPaths = (patchText: string): ReadonlyArray<string> => {
+  const paths: Array<string> = []
+  for (const line of patchText.split("\n")) {
+    const match = /^\*\*\* (?:Add|Update) File: (.+)$/.exec(line)
+    if (match?.[1] !== undefined) paths.push(match[1])
+    const move = /^\*\*\* Move to: (.+)$/.exec(line)
+    if (move?.[1] !== undefined) paths.push(move[1])
+  }
+  return [...new Set(paths)]
+}
+
+const inputPaths = (tool: string, input: unknown): ReadonlyArray<string> => {
+  if (tool === "write" || tool === "edit") {
+    const filePath = stringProperty(input, "filePath") ?? stringProperty(input, "path")
+    return filePath === undefined ? [] : [filePath]
+  }
+  if (tool === "apply_patch" || tool === "patch") {
+    const patchText = stringProperty(input, "patchText")
+    return patchText === undefined ? [] : patchPaths(patchText)
+  }
+  return []
+}
+
+/** Register prospective snapshots and post-write Effect pattern feedback hooks. */
+export const registerPatternEnforcement = async (
+  context: Plugin.Context,
+  patterns: ReadonlyArray<Pattern.Value>,
+  isEnabled: (agent: unknown) => boolean = () => true
+): Promise<void> => {
+  const pending = new Map<string, PendingWrite>()
+
+  await context.tool.hook("execute.before", async (event) => {
+    try {
+      if (!isEnabled(event.agent)) {
+        pending.delete(event.id)
+        return
+      }
+      const paths = inputPaths(event.tool, event.input)
+      if (paths.length === 0) return
+      const session = await context.session.get({ sessionID: event.sessionID })
+      pending.set(event.id, {
+        files: await Promise.all(
+          paths.map((filePath) => snapshotFile(session.location.directory, filePath))
+        ),
+        fullFile: event.tool === "write"
+      })
+    } catch {
+      pending.delete(event.id)
+    }
+  })
+
+  await context.tool.hook("execute.after", async (event) => {
+    const write = pending.get(event.id)
+    pending.delete(event.id)
+    if (!isEnabled(event.agent) || event.status !== "completed" || write === undefined) return
+
+    try {
+      const feedback = (await Promise.all(write.files.map(async (file) => {
+        const projection = await actualProjection(file)
+        if (projection === undefined || projection.changedSpans?.length === 0) return undefined
+        const input = write.fullFile
+          ? { ...projection, changedSpans: [{ start: 0, end: projection.content.length }] }
+          : projection
+        const matched = patterns.filter((pattern) =>
+          matchesPattern("edit", input, "after", pattern)
+        )
+        return matched.length === 0 ? undefined : buildPatternFeedback(matched, file.filePath)
+      }))).filter((message): message is string => message !== undefined)
+      if (feedback.length === 0) return
+      const message = feedback.join("\n\n---\n\n")
+      const content = event.result.content
+      event.result = {
+        ...event.result,
+        content: Array.isArray(content)
+          ? [...content, { type: "text", text: message }]
+          : typeof content === "string"
+          ? `${content}\n\n${message}`
+          : message
+      }
+    } catch {
+      // Pattern feedback must never turn an advisory check into a failed write.
+    }
+  })
+}

package/src/frontmatter.ts

@@ -0,0 +1,34 @@
+import YAML from "yaml"
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/
+const SAFE_VALUE_RE = /^[\w\s.\-/]+$/
+
+const isAlreadyQuoted = (value: string): boolean =>
+  (value.startsWith("'") && value.endsWith("'"))
+  || (value.startsWith('"') && value.endsWith('"'))
+
+const quoteYamlValue = (line: string): string => {
+  const match = line.match(/^(\s*)(\w[\w-]*):\s+(.+)$/)
+  if (match === null) return line
+  const [, indent, key, value] = match
+  if (indent === undefined || key === undefined || value === undefined) return line
+  if (isAlreadyQuoted(value) || SAFE_VALUE_RE.test(value)) return line
+  const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')
+  return `${indent}${key}: "${escaped}"`
+}
+
+/** Parse YAML frontmatter, including unquoted detector expressions used by the pattern catalog. */
+export const parseFrontmatter = (content: string): Record<string, unknown> => {
+  const match = content.match(FRONTMATTER_RE)
+  if (match?.[1] === undefined) return {}
+  try {
+    const parsed: unknown = YAML.parse(match[1].split("\n").map(quoteYamlValue).join("\n"))
+    return typeof parsed === "object" && parsed !== null ? { ...parsed } : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Remove YAML frontmatter and return the trimmed Markdown body. */
+export const extractBody = (content: string): string =>
+  content.replace(/^---\n[\s\S]*?\n---\n?/, "").trim()

package/src/guidance.ts

@@ -0,0 +1,66 @@
+import { readdir, readFile } from "node:fs/promises"
+import path from "node:path"
+
+import { Pattern } from "./pattern.ts"
+
+const LEVEL_ORDER: Record<Pattern.Value["level"], number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  warning: 3,
+  info: 4
+}
+
+/** Load bundled guidance documents in deterministic filename order. */
+export const loadGuidance = async (guidanceDirectory: string): Promise<string> => {
+  const entries = (await readdir(guidanceDirectory)).filter((entry) => entry.endsWith(".md"))
+    .toSorted()
+  const documents = (await Promise.all(
+    entries.map((entry) => readFile(path.join(guidanceDirectory, entry), "utf8"))
+  ))
+    .map((content) => content.trim())
+    .filter((content) => content.length > 0)
+  return documents.join("\n\n---\n\n")
+}
+
+const guidanceWithSkillHints = (pattern: Pattern.Value): string => {
+  const hints =
+    pattern.suggestedSkills?.map((skill) =>
+      `If you have not loaded the \`${skill}\` skill, load it before continuing.`
+    ) ?? []
+  return hints.length === 0 ? pattern.guidance : `${pattern.guidance}\n\n${hints.join("\n")}`
+}
+
+/** Compose one severity-ordered, model-visible review request for a completed write. */
+export const buildPatternFeedback = (
+  patterns: ReadonlyArray<Pattern.Value>,
+  filePath: string
+): string => {
+  const selected = [...patterns].toSorted((left, right) =>
+    LEVEL_ORDER[left.level] - LEVEL_ORDER[right.level]
+  )
+  return [
+    "opencode-effect-enforcer review request:",
+    `File: \`${filePath}\``,
+    "",
+    "I noticed potential Effect-pattern issues in the write you just completed.",
+    "Inspect this change now. If a warning is valid, revise the code before continuing.",
+    "If it is a false positive or intentional exception, briefly say so and continue.",
+    "",
+    "Matched patterns:",
+    ...selected.map((pattern) => `- ${pattern.name} [${pattern.level}]: ${pattern.description}`),
+    "",
+    "Relevant guidance:",
+    ...selected.map((pattern) => `## ${pattern.name}\n${guidanceWithSkillHints(pattern)}`)
+  ].join("\n")
+}
+
+/** Add OpenCode-specific operating instructions to the copied Effect guidance. */
+export const withPluginPolicy = (guidance: string): string =>
+  [
+    guidance,
+    "OpenCode Effect Enforcer policy:",
+    "- The bundled effect-* skills are available through OpenCode's skill tool. Load at least four relevant skills before planning or writing Effect code.",
+    "- Treat post-write pattern feedback as an immediate review request. Fix valid findings before continuing.",
+    "- Pattern findings are advisory: explain intentional exceptions or false positives instead of changing correct code."
+  ].join("\n\n---\n\n")

package/src/index.ts

@@ -0,0 +1,38 @@
+import { Plugin } from "@opencode-ai/plugin"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { consumeAgentOptOut } from "./agent-policy.ts"
+import { registerPatternEnforcement } from "./enforcer.ts"
+import { loadGuidance, withPluginPolicy } from "./guidance.ts"
+import { loadPatterns } from "./pattern-catalog.ts"
+import { loadSkills } from "./skills.ts"
+
+const packageDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+export default Plugin.define({
+  id: "opencode.effect-enforcer",
+  setup: async (context) => {
+    const disabledAgents = new Set<unknown>()
+    const [guidance, patterns, skills] = await Promise.all([
+      loadGuidance(path.join(packageDirectory, "guidance")),
+      loadPatterns(path.join(packageDirectory, "patterns")),
+      loadSkills(path.join(packageDirectory, "skills"))
+    ])
+
+    await context.agent.transform((draft) => {
+      disabledAgents.clear()
+      for (const agent of draft.list()) {
+        if (consumeAgentOptOut(agent)) disabledAgents.add(agent.id)
+      }
+    })
+    await context.skill.transform((draft) => {
+      for (const skill of skills) draft.add(skill)
+    })
+    await context.session.hook("context", (event) => {
+      if (disabledAgents.has(event.agent)) return
+      event.system.push({ type: "text", text: withPluginPolicy(guidance) })
+    })
+    await registerPatternEnforcement(context, patterns, (agent) => !disabledAgents.has(agent))
+  }
+})

package/src/pattern-catalog.ts

@@ -0,0 +1,115 @@
+import type { Rule as AstGrepRuleDefinition } from "@ast-grep/napi"
+import { readdir, readFile, stat } from "node:fs/promises"
+import path from "node:path"
+
+import { extractBody, parseFrontmatter } from "./frontmatter.ts"
+import { Pattern, type PatternLevel } from "./pattern.ts"
+
+const SKIPPED_FILES = ["CLAUDE", "AGENTS", "GEMINI", "README"]
+const LEVELS: ReadonlySet<string> = new Set(["critical", "high", "medium", "warning", "info"])
+
+const string = (value: unknown): string | undefined => typeof value === "string" ? value : undefined
+const strings = (value: unknown): ReadonlyArray<string> | undefined =>
+  Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined
+const astRule = (value: unknown): value is AstGrepRuleDefinition =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+const astRules = (value: unknown): ReadonlyArray<AstGrepRuleDefinition> | undefined => {
+  if (astRule(value)) return [value]
+  return Array.isArray(value) && value.length > 0 && value.every(astRule) ? value : undefined
+}
+
+const astConstraints = (value: unknown): Record<string, AstGrepRuleDefinition> | undefined => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const entries = Object.entries(value)
+  return entries.every(([, rule]) => astRule(rule))
+    ? Object.fromEntries(entries) as Record<string, AstGrepRuleDefinition>
+    : undefined
+}
+
+const detector = (
+  raw: Record<string, unknown>
+): Pattern.RegexDetector | Pattern.AstDetector | undefined => {
+  if (raw.detector === "ast") {
+    const rules = astRules(raw.rule) ?? astRules(raw.rules)
+    const constraints = astConstraints(raw.constraints)
+    if (rules !== undefined) return new Pattern.AstDetector({ patterns: [], rules, constraints })
+    const patterns = typeof raw.pattern === "string" ? [raw.pattern] : strings(raw.pattern)
+    if (patterns === undefined || patterns.length === 0) return undefined
+    const inside = string(raw.inside)
+    return new Pattern.AstDetector({ patterns, ...(inside === undefined ? {} : { inside }) })
+  }
+
+  const expression = string(raw.pattern)
+  if (expression === undefined) return undefined
+  try {
+    new RegExp(expression)
+  } catch {
+    return undefined
+  }
+  return new Pattern.RegexDetector({
+    pattern: expression,
+    matchInComments: raw.matchInComments === true || raw.matchInComments === "true"
+  })
+}
+
+const toPattern = (filePath: string, content: string): Pattern.Value | undefined => {
+  const raw = parseFrontmatter(content)
+  const name = string(raw.name)
+  const selectedDetector = detector(raw)
+  const toolRegex = string(raw.tool) ?? ".*"
+  if (name === undefined || selectedDetector === undefined) return undefined
+  try {
+    new RegExp(toolRegex)
+  } catch {
+    return undefined
+  }
+  const rawLevel = string(raw.level) ?? "info"
+  return new Pattern.Value({
+    name,
+    description: string(raw.description) ?? "",
+    event: string(raw.event)?.toLowerCase() === "after" ? "after" : "before",
+    toolRegex,
+    level: (LEVELS.has(rawLevel) ? rawLevel : "info") as PatternLevel,
+    glob: string(raw.glob),
+    ignoreGlob: strings(raw.ignoreGlob),
+    detector: selectedDetector,
+    guidance: extractBody(content),
+    suggestedSkills: strings(raw.suggestSkills),
+    sourcePath: filePath
+  })
+}
+
+const isSkipped = (name: string): boolean =>
+  SKIPPED_FILES.some((prefix) =>
+    name.startsWith(prefix) || name.toLowerCase() === `${prefix.toLowerCase()}.md`
+  )
+
+/** Recursively load valid Markdown pattern definitions in deterministic path order. */
+export const loadPatterns = async (
+  patternsDirectory: string
+): Promise<ReadonlyArray<Pattern.Value>> => {
+  const walk = async (directory: string): Promise<ReadonlyArray<Pattern.Value>> => {
+    let entries: ReadonlyArray<string>
+    try {
+      entries = await readdir(directory)
+    } catch {
+      return []
+    }
+    const nested = await Promise.all(entries.map(async (entry) => {
+      const target = path.join(directory, entry)
+      try {
+        const info = await stat(target)
+        if (info.isDirectory()) return walk(target)
+        if (!info.isFile() || !entry.endsWith(".md") || isSkipped(entry)) return []
+        const pattern = toPattern(target, await readFile(target, "utf8"))
+        return pattern === undefined ? [] : [pattern]
+      } catch {
+        return []
+      }
+    }))
+    return nested.flat()
+  }
+  return (await walk(patternsDirectory)).toSorted((left, right) =>
+    left.sourcePath.localeCompare(right.sourcePath)
+  )
+}

package/src/pattern-matcher.ts

@@ -0,0 +1,178 @@
+import { Lang, type NapiConfig, parse, type Rule as AstGrepRuleDefinition } from "@ast-grep/napi"
+import picomatch from "picomatch"
+
+import { type MatcherInput, Pattern, type Span } from "./pattern.ts"
+
+/** Blank JavaScript comments while preserving source offsets, strings, and line breaks. */
+export const stripComments = (source: string): string => {
+  const output: Array<string> = []
+  let index = 0
+  const at = (current: number) => source.charAt(current)
+  const keep = () => {
+    output.push(at(index))
+    index += 1
+  }
+  const blank = () => {
+    output.push(at(index) === "\n" ? "\n" : " ")
+    index += 1
+  }
+
+  while (index < source.length) {
+    const current = at(index)
+    const next = at(index + 1)
+    if (current === "'" || current === '"') {
+      const quote = current
+      keep()
+      while (index < source.length && at(index) !== quote) {
+        if (at(index) === "\\" && index + 1 < source.length) keep()
+        keep()
+      }
+      if (index < source.length) keep()
+      continue
+    }
+    if (current === "`") {
+      keep()
+      while (index < source.length && at(index) !== "`") {
+        if (at(index) === "\\" && index + 1 < source.length) keep()
+        keep()
+      }
+      if (index < source.length) keep()
+      continue
+    }
+    if (current === "/" && next === "/") {
+      blank()
+      blank()
+      while (index < source.length && at(index) !== "\n") blank()
+      continue
+    }
+    if (current === "/" && next === "*") {
+      blank()
+      blank()
+      while (index < source.length) {
+        if (at(index) === "*" && at(index + 1) === "/") {
+          blank()
+          blank()
+          break
+        }
+        blank()
+      }
+      continue
+    }
+    keep()
+  }
+  return output.join("")
+}
+
+const location = (source: string, start: number, end: number): Pattern.MatchLocation => {
+  const before = source.slice(0, start)
+  const previousBreak = before.lastIndexOf("\n")
+  return new Pattern.MatchLocation({
+    start,
+    end,
+    line: before.split("\n").length,
+    column: start - (previousBreak === -1 ? 0 : previousBreak + 1) + 1,
+    snippet: (source.slice(start, end).split("\n")[0] ?? "").trim()
+  })
+}
+
+const language = (filePath: string): Lang | undefined => {
+  if (filePath.endsWith(".tsx") || filePath.endsWith(".jsx")) return Lang.Tsx
+  if (filePath.endsWith(".ts")) return Lang.TypeScript
+  if (filePath.endsWith(".js")) return Lang.JavaScript
+  return undefined
+}
+
+const astLocations = (
+  detector: Pattern.AstDetector,
+  source: string,
+  filePath: string | undefined
+): ReadonlyArray<Pattern.MatchLocation> => {
+  if (filePath === undefined) return []
+  const lang = language(filePath)
+  if (lang === undefined) return []
+  try {
+    const root = parse(lang, source).root()
+    const find = (matcher: string | NapiConfig) =>
+      root.findAll(matcher).map((node) =>
+        location(source, node.range().start.index, node.range().end.index)
+      )
+    const legacy = detector.patterns.flatMap((candidate) =>
+      find(
+        detector.inside === undefined ? candidate : {
+          rule: { pattern: candidate, inside: { pattern: detector.inside, stopBy: "end" } }
+        }
+      )
+    )
+    const rules = (detector.rules ?? []).flatMap((rule: AstGrepRuleDefinition) =>
+      find(
+        detector.constraints === undefined
+          ? { rule }
+          : { rule, constraints: detector.constraints }
+      )
+    )
+    return [...legacy, ...rules]
+  } catch {
+    return []
+  }
+}
+
+const regexLocations = (
+  detector: Pattern.RegexDetector,
+  source: string
+): ReadonlyArray<Pattern.MatchLocation> => {
+  const matchSource = detector.matchInComments ? source : stripComments(source)
+  try {
+    const regex = new RegExp(detector.pattern, "g")
+    return [...matchSource.matchAll(regex)].flatMap((match) =>
+      match.index === undefined || match[0].length === 0
+        ? []
+        : [location(source, match.index, match.index + match[0].length)]
+    )
+  } catch {
+    return []
+  }
+}
+
+const intersects = (left: Span, right: Span): boolean =>
+  left.start < right.end && right.start < left.end
+
+/** Find detector matches that satisfy event, tool, path, and changed-span constraints. */
+export const findPatternMatches = (
+  toolName: string,
+  input: MatcherInput,
+  event: "before" | "after",
+  pattern: Pattern.Value
+): ReadonlyArray<Pattern.MatchLocation> => {
+  try {
+    if (pattern.event !== event || !new RegExp(pattern.toolRegex).test(toolName)) return []
+    if (
+      pattern.glob !== undefined
+      && (input.filePath === undefined || !picomatch(pattern.glob)(input.filePath))
+    ) return []
+    const filePath = input.filePath
+    if (
+      filePath !== undefined
+      && pattern.ignoreGlob?.some((glob) => picomatch(glob)(filePath)) === true
+    ) {
+      return []
+    }
+  } catch {
+    return []
+  }
+  const matches = pattern.detector instanceof Pattern.AstDetector
+    ? astLocations(pattern.detector, input.content, input.filePath)
+    : regexLocations(pattern.detector, input.content)
+  return input.changedSpans === undefined
+    ? matches
+    : matches.filter((match) =>
+      input.changedSpans?.some((span) => intersects(match, span)) === true
+    )
+}
+
+/** Determine whether a pattern matches normalized input. */
+export const matchesPattern = (
+  toolName: string,
+  input: MatcherInput,
+  event: "before" | "after",
+  pattern: Pattern.Value
+): boolean => findPatternMatches(toolName, input, event, pattern).length > 0

package/src/pattern.ts

@@ -0,0 +1,97 @@
+import type { NapiConfig, Rule as AstGrepRuleDefinition } from "@ast-grep/napi"
+
+/** Pattern severity controls feedback ordering. */
+export type PatternLevel = "critical" | "high" | "medium" | "warning" | "info"
+
+/** A half-open source span. */
+export interface Span {
+  readonly start: number
+  readonly end: number
+}
+
+/** Normalized content passed to pattern detectors. */
+export interface MatcherInput {
+  readonly filePath?: string
+  readonly content: string
+  readonly changedSpans?: ReadonlyArray<Span>
+}
+
+/** Pattern definitions loaded from the bundled Markdown catalog. */
+export namespace Pattern {
+  /** A source location matched by a detector. */
+  export class MatchLocation implements Span {
+    readonly start: number
+    readonly end: number
+    readonly line: number
+    readonly column: number
+    readonly snippet: string
+
+    constructor(fields: MatchLocation) {
+      this.start = fields.start
+      this.end = fields.end
+      this.line = fields.line
+      this.column = fields.column
+      this.snippet = fields.snippet
+    }
+  }
+
+  /** A regular-expression detector. */
+  export class RegexDetector {
+    readonly pattern: string
+    readonly matchInComments: boolean
+
+    constructor(fields: RegexDetector) {
+      this.pattern = fields.pattern
+      this.matchInComments = fields.matchInComments
+    }
+  }
+
+  /** An ast-grep detector supporting legacy patterns and complete rules. */
+  export class AstDetector {
+    readonly patterns: ReadonlyArray<string>
+    readonly rules: ReadonlyArray<AstGrepRuleDefinition> | undefined
+    readonly constraints: NapiConfig["constraints"] | undefined
+    readonly inside: string | undefined
+
+    constructor(fields: {
+      readonly patterns: ReadonlyArray<string>
+      readonly rules?: ReadonlyArray<AstGrepRuleDefinition>
+      readonly constraints?: NapiConfig["constraints"]
+      readonly inside?: string
+    }) {
+      this.patterns = fields.patterns
+      this.rules = fields.rules
+      this.constraints = fields.constraints
+      this.inside = fields.inside
+    }
+  }
+
+  /** A complete enforcement pattern and its model-facing remediation guidance. */
+  export class Value {
+    readonly name: string
+    readonly description: string
+    readonly event: "before" | "after"
+    readonly toolRegex: string
+    readonly level: PatternLevel
+    readonly glob: string | undefined
+    readonly ignoreGlob: ReadonlyArray<string> | undefined
+    readonly detector: RegexDetector | AstDetector
+    readonly guidance: string
+    readonly suggestedSkills: ReadonlyArray<string> | undefined
+    readonly sourcePath: string
+
+    constructor(fields: Value) {
+      this.name = fields.name
+      this.description = fields.description
+      this.event = fields.event
+      this.toolRegex = fields.toolRegex
+      this.level = fields.level
+      this.glob = fields.glob
+      this.ignoreGlob = fields.ignoreGlob
+      this.detector = fields.detector
+      this.guidance = fields.guidance
+      this.suggestedSkills = fields.suggestedSkills
+      this.sourcePath = fields.sourcePath
+    }
+  }
+}

package/src/skills.ts

@@ -0,0 +1,29 @@
+import { Skill } from "@opencode-ai/plugin"
+import { readdir, readFile } from "node:fs/promises"
+import path from "node:path"
+
+import { extractBody, parseFrontmatter } from "./frontmatter.ts"
+
+/** Load bundled directory skills as OpenCode V2 skill definitions. */
+export const loadSkills = async (skillsDirectory: string): Promise<ReadonlyArray<Skill.Info>> => {
+  const entries = await readdir(skillsDirectory, { withFileTypes: true })
+  const skills = await Promise.all(
+    entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+      const location = path.join(skillsDirectory, entry.name, "SKILL.md")
+      const markdown = await readFile(location, "utf8")
+      const frontmatter = parseFrontmatter(markdown)
+      const displayName = typeof frontmatter.name === "string" ? frontmatter.name : entry.name
+      const description = typeof frontmatter.description === "string"
+        ? frontmatter.description
+        : undefined
+      return Skill.Info.make({
+        id: Skill.ID.make(entry.name),
+        name: Skill.Name.make(displayName),
+        description,
+        location: Skill.Info.fields.location.make(location),
+        content: extractBody(markdown)
+      })
+    })
+  )
+  return skills.toSorted((left, right) => left.id.localeCompare(right.id))
+}