Skip to content

Commit e09f983

Browse files
opencodeclaude
andcommitted
feat(core): SkillCatalog read model, consuming SkillV2's own merge
TKT-323 SkillCatalog, core layer. Per the lead's ruling on the shared- pure-function shape: the catalog must consume the exact mechanism that decides which skill wins a name collision, never re-derive its own ordering that "should" match it. - SkillV2.Service gains `entries()`, exposing the full unfiltered `mergeSkills` result (winners AND shadowed losers, with provenance). `list()` now delegates to it and filters to winners -- identical behavior to before, proven by the pre-existing test passing unchanged. - SkillCatalog.Service.list() consumes that same `entries()` call and adds target attribution: a `directory` source's path is walked up against `ConfigDocument.listTargets()` to find the deepest enclosing target directory ("closer overrides farther", same rule mergeSkills itself resolves collisions with), falling back to the global target when no project tier encloses it (e.g. a source declared from outside the project tree, or a bare `.opencode` tier with no co-located config file -- listTargets()'s chunk-1 scope doesn't list those as targets themselves). `url`/`embedded` sources carry no target -- there is no location to attribute. - Delete-the-fix regression test for the ordering-perturbation shape Ethan specified: two sources with a colliding skill name, registered in one order then the reverse, confirming SkillV2.list()'s winner and the catalog's winner move together both times -- not just agree once by coincidence. Also delete-the-fix for the target-attribution fallback specifically (confirmed red without it, green with it) -- none of the other attribution tests happened to exercise that branch. Core layer only. Protocol group extension and settings-v2 UI are the next slice. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JJQrqYMv43CrdbjpTT7884
1 parent 8e72016 commit e09f983

5 files changed

Lines changed: 359 additions & 3 deletions

File tree

‎packages/core/src/skill-catalog.ts‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
export * as SkillCatalog from "./skill-catalog"
2+
3+
import path from "path"
4+
import { Context, Effect, Layer } from "effect"
5+
import { SkillCatalog as SkillCatalogSchema } from "@opencode-ai/schema/skill-catalog"
6+
import type { ConfigDocument as ConfigDocumentSchema } from "@opencode-ai/schema/config-document"
7+
import { makeLocationNode } from "./effect/app-node"
8+
import { ConfigDocument } from "./config/document"
9+
import { SkillV2 } from "./skill"
10+
11+
export const Entry = SkillCatalogSchema.Entry
12+
export type Entry = SkillCatalogSchema.Entry
13+
14+
export interface Interface {
15+
/** Every skill this location knows about -- winners AND shadowed losers, with provenance and
16+
* (for directory sources) an enclosing config target. Consumes `SkillV2.Service.entries()`
17+
* directly rather than re-deriving its own load-then-merge walk: this catalog reports what
18+
* `SkillV2.list()` decides, it never decides on its own (lead ruling, TKT-323 diary 2554,
19+
* "truth flows runtime -> catalog, never the reverse"). */
20+
readonly list: () => Effect.Effect<Entry[]>
21+
}
22+
23+
export class Service extends Context.Service<Service, Interface>()("@opencode/v2/SkillCatalog") {}
24+
25+
// The deepest target whose OWN directory encloses (or equals) `sourceDirectory` -- "deepest"
26+
// because a project tier nested inside another project tier must win over the outer one, same
27+
// "closer overrides farther" rule `mergeSkills` itself resolves collisions with. Falls back to
28+
// the global target, which structurally encloses every location: a directory source with no
29+
// project-tier target above it (e.g. a bare `.opencode` folder with no co-located opencode.json,
30+
// walked past by `ConfigDocument.listTargets()`'s own chunk-1 scope -- see that method's doc
31+
// comment) still has SOME enclosing config, and reporting undefined there would be a client-
32+
// visible regression from "attributed to global" to "attributed to nothing" for a case that was
33+
// never really ambiguous.
34+
function findEnclosingTarget(
35+
sourceDirectory: string,
36+
targets: readonly ConfigDocumentSchema.TargetSummary[],
37+
): ConfigDocumentSchema.TargetSummary | undefined {
38+
let best: ConfigDocumentSchema.TargetSummary | undefined
39+
let bestDepth = -1
40+
for (const target of targets) {
41+
const targetDirectory = path.dirname(target.path)
42+
const relative = path.relative(targetDirectory, sourceDirectory)
43+
const encloses = relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
44+
if (!encloses) continue
45+
const depth = targetDirectory.split(path.sep).length
46+
if (depth > bestDepth) {
47+
best = target
48+
bestDepth = depth
49+
}
50+
}
51+
return best ?? targets.find((target) => target.kind === "global")
52+
}
53+
54+
const layer = Layer.effect(
55+
Service,
56+
Effect.gen(function* () {
57+
const skills = yield* SkillV2.Service
58+
const documents = yield* ConfigDocument.Service
59+
60+
const list: Interface["list"] = Effect.fn("SkillCatalog.list")(function* () {
61+
const merged = yield* skills.entries()
62+
const targets = yield* documents.listTargets()
63+
64+
return merged.map(
65+
(entry) =>
66+
new Entry({
67+
skill: entry.skill,
68+
source: entry.source,
69+
sourceIndex: entry.sourceIndex,
70+
shadowedBy: entry.shadowedBy,
71+
target:
72+
entry.source.type === "directory" ? findEnclosingTarget(entry.source.path, targets)?.id : undefined,
73+
}),
74+
)
75+
})
76+
77+
return Service.of({ list })
78+
}),
79+
)
80+
81+
export const node = makeLocationNode({ service: Service, layer, deps: [SkillV2.node, ConfigDocument.node] })

‎packages/core/src/skill.ts‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,12 @@ export type Draft = {
4848

4949
export interface Interface extends State.Transformable<Draft> {
5050
readonly sources: () => Effect.Effect<Source[]>
51+
/** The full result of `mergeSkills` over this location's currently-loaded sources -- winners
52+
* AND shadowed losers, with provenance. `list()` filters this to winners; `SkillCatalog` (TKT-323)
53+
* reports the whole thing. Both consume this exact Effect rather than each re-deriving their own
54+
* load-then-merge walk, so they cannot disagree about which skill wins a name collision (see
55+
* `mergeSkills`'s own doc comment). */
56+
readonly entries: () => Effect.Effect<MergeEntry[]>
5157
readonly list: () => Effect.Effect<Info[]>
5258
}
5359

@@ -151,7 +157,7 @@ const layer = Layer.effect(
151157
// QUESTION(Dax): Should local skill sources invalidate on filesystem watch
152158
// events, following the reload policy chosen for other context sources?
153159
const cache = new Map<string, Info[]>()
154-
const list = Effect.fn("SkillV2.list")(function* () {
160+
const entries = Effect.fn("SkillV2.entries")(function* () {
155161
const loaded: LoadedSource[] = []
156162
for (const source of state.get().sources) {
157163
const key = Source.key(source)
@@ -160,8 +166,9 @@ const layer = Layer.effect(
160166
loaded.push({ source, skills })
161167
}
162168
return mergeSkills(loaded)
163-
.filter((entry) => !entry.shadowedBy)
164-
.map((entry) => entry.skill)
169+
})
170+
const list = Effect.fn("SkillV2.list")(function* () {
171+
return (yield* entries()).filter((entry) => !entry.shadowedBy).map((entry) => entry.skill)
165172
})
166173

167174
return Service.of({
@@ -170,6 +177,7 @@ const layer = Layer.effect(
170177
sources: Effect.fn("SkillV2.sources")(function* () {
171178
return state.get().sources
172179
}),
180+
entries,
173181
list,
174182
})
175183
}),
Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
import fs from "fs/promises"
2+
import path from "path"
3+
import { describe, expect } from "bun:test"
4+
import { Effect, Layer } from "effect"
5+
import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
6+
import { LayerNode } from "@opencode-ai/core/effect/layer-node"
7+
import { ConfigDocument } from "@opencode-ai/core/config/document"
8+
import { Global } from "@opencode-ai/core/global"
9+
import { Location } from "@opencode-ai/core/location"
10+
import { AbsolutePath } from "@opencode-ai/core/schema"
11+
import { SkillV2 } from "@opencode-ai/core/skill"
12+
import { SkillCatalog } from "@opencode-ai/core/skill-catalog"
13+
import { SkillDiscovery } from "@opencode-ai/core/skill/discovery"
14+
import { location } from "./fixture/location"
15+
import { tmpdir } from "./fixture/tmpdir"
16+
import { testEffect } from "./lib/effect"
17+
18+
const discovery = Layer.succeed(SkillDiscovery.Service, SkillDiscovery.Service.of({ pull: () => Effect.succeed([]) }))
19+
20+
function testLayer(directory: string, globalDirectory = path.join(directory, "global"), projectDirectory = directory) {
21+
const locationLayer = Layer.succeed(
22+
Location.Service,
23+
Location.Service.of(
24+
location({ directory: AbsolutePath.make(directory) }, { projectDirectory: AbsolutePath.make(projectDirectory) }),
25+
),
26+
)
27+
return AppNodeBuilder.build(LayerNode.group([SkillCatalog.node, SkillV2.node, ConfigDocument.node]), [
28+
[Location.node, locationLayer],
29+
[Global.node, Global.layerWith({ config: globalDirectory })],
30+
[SkillDiscovery.node, discovery],
31+
])
32+
}
33+
34+
function withTmp<A, E, R>(run: (tmp: { path: string }) => Effect.Effect<A, E, R>) {
35+
return Effect.acquireRelease(
36+
Effect.promise(() => tmpdir()),
37+
(tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
38+
).pipe(Effect.flatMap(run))
39+
}
40+
41+
function write(directory: string, name: string, description: string) {
42+
return fs.writeFile(
43+
path.join(directory, name, "SKILL.md"),
44+
`---\nname: ${name}\ndescription: ${description}\n---\n# ${name}`,
45+
)
46+
}
47+
48+
const it = testEffect(Layer.empty)
49+
50+
describe("SkillCatalog", () => {
51+
it.live("reports both the winner and the shadowed loser, with provenance", () =>
52+
withTmp((tmp) =>
53+
Effect.gen(function* () {
54+
const first = path.join(tmp.path, "first")
55+
const second = path.join(tmp.path, "second")
56+
yield* Effect.promise(async () => {
57+
await fs.mkdir(path.join(first, "review"), { recursive: true })
58+
await fs.mkdir(path.join(second, "review"), { recursive: true })
59+
await write(first, "review", "First")
60+
await write(second, "review", "Second")
61+
})
62+
63+
return yield* Effect.gen(function* () {
64+
const skills = yield* SkillV2.Service
65+
yield* skills.transform((editor) => {
66+
editor.source({ type: "directory", path: AbsolutePath.make(first) })
67+
editor.source({ type: "directory", path: AbsolutePath.make(second) })
68+
})
69+
70+
const catalog = yield* SkillCatalog.Service
71+
const entries = yield* catalog.list()
72+
73+
expect(entries).toHaveLength(2)
74+
const winner = entries.find((entry) => !entry.shadowedBy)!
75+
const loser = entries.find((entry) => entry.shadowedBy)!
76+
expect(winner.skill.description).toBe("Second")
77+
expect(winner.sourceIndex).toBe(1)
78+
expect(loser.skill.description).toBe("First")
79+
expect(loser.sourceIndex).toBe(0)
80+
expect(loser.shadowedBy).toEqual({ source: { type: "directory", path: AbsolutePath.make(second) }, sourceIndex: 1 })
81+
82+
// Same fact `SkillV2.list()` reports (winners only) -- the catalog must not disagree.
83+
const list = yield* skills.list()
84+
expect(list).toHaveLength(1)
85+
expect(list[0]!.description).toBe("Second")
86+
}).pipe(Effect.provide(testLayer(tmp.path))).pipe(Effect.orDie)
87+
}),
88+
),
89+
)
90+
91+
// Delete-the-fix, the shape Ethan's ruling specified: perturb which source is registered LAST
92+
// (closer-wins) and confirm the winner moves on BOTH surfaces together. A catalog computed by
93+
// its own independent walk could pass the test above by coincidence while still disagreeing
94+
// with SkillV2.list() under a different ordering -- this is what rules that out. Both calls
95+
// read `SkillV2.Service.entries()`, so there is no ordering under which they COULD diverge; if
96+
// a future change made the catalog re-derive its own merge, this is the test that would catch it.
97+
it.live("perturbing registration order moves the winner on SkillV2.list() and the catalog together", () =>
98+
withTmp((tmp) =>
99+
Effect.gen(function* () {
100+
const first = path.join(tmp.path, "first")
101+
const second = path.join(tmp.path, "second")
102+
yield* Effect.promise(async () => {
103+
await fs.mkdir(path.join(first, "review"), { recursive: true })
104+
await fs.mkdir(path.join(second, "review"), { recursive: true })
105+
await write(first, "review", "First")
106+
await write(second, "review", "Second")
107+
})
108+
109+
return yield* Effect.gen(function* () {
110+
const skills = yield* SkillV2.Service
111+
// Reversed from the test above: `first` registered LAST, so it should win this time.
112+
yield* skills.transform((editor) => {
113+
editor.source({ type: "directory", path: AbsolutePath.make(second) })
114+
editor.source({ type: "directory", path: AbsolutePath.make(first) })
115+
})
116+
117+
const catalog = yield* SkillCatalog.Service
118+
const entries = yield* catalog.list()
119+
const winner = entries.find((entry) => !entry.shadowedBy)!
120+
expect(winner.skill.description).toBe("First")
121+
122+
const list = yield* skills.list()
123+
expect(list[0]!.description).toBe("First")
124+
}).pipe(Effect.provide(testLayer(tmp.path))).pipe(Effect.orDie)
125+
}),
126+
),
127+
)
128+
129+
it.live("a directory source under the project root is attributed to the project target", () =>
130+
withTmp((tmp) =>
131+
Effect.gen(function* () {
132+
const skillDir = path.join(tmp.path, "skill")
133+
yield* Effect.promise(async () => {
134+
await fs.mkdir(path.join(skillDir, "deploy"), { recursive: true })
135+
await write(skillDir, "deploy", "Deploy")
136+
await fs.writeFile(path.join(tmp.path, "opencode.json"), "{}")
137+
})
138+
139+
return yield* Effect.gen(function* () {
140+
const skills = yield* SkillV2.Service
141+
yield* skills.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(skillDir) }))
142+
143+
const catalog = yield* SkillCatalog.Service
144+
const entries = yield* catalog.list()
145+
expect(entries).toHaveLength(1)
146+
expect(entries[0]!.target).toBeDefined()
147+
148+
const documents = yield* ConfigDocument.Service
149+
const project = (yield* documents.listTargets()).find((target) => target.kind === "project")!
150+
expect(entries[0]!.target).toBe(project.id)
151+
}).pipe(Effect.provide(testLayer(tmp.path))).pipe(Effect.orDie)
152+
}),
153+
),
154+
)
155+
156+
it.live("a bare .opencode-tier directory with no co-located config falls back to the nearest enclosing target", () =>
157+
withTmp((tmp) =>
158+
Effect.gen(function* () {
159+
// Mirrors config/plugin/skill.ts's own convention: a `.opencode/skill` directory with no
160+
// opencode.json(c) sitting IN THAT SAME directory. `ConfigDocument.listTargets()` (chunk
161+
// 1 scope) never lists `.opencode` directories as targets themselves -- see that method's
162+
// own doc comment -- so this directory source has no CO-LOCATED target to match exactly.
163+
const dotOpencode = path.join(tmp.path, ".opencode")
164+
const skillDir = path.join(dotOpencode, "skill")
165+
yield* Effect.promise(async () => {
166+
await fs.mkdir(path.join(skillDir, "deploy"), { recursive: true })
167+
await write(skillDir, "deploy", "Deploy")
168+
await fs.writeFile(path.join(tmp.path, "opencode.json"), "{}")
169+
})
170+
171+
return yield* Effect.gen(function* () {
172+
const skills = yield* SkillV2.Service
173+
yield* skills.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(skillDir) }))
174+
175+
const catalog = yield* SkillCatalog.Service
176+
const entries = yield* catalog.list()
177+
178+
const documents = yield* ConfigDocument.Service
179+
const project = (yield* documents.listTargets()).find((target) => target.kind === "project")!
180+
// Not undefined, and not the global fallback either -- the project opencode.json one
181+
// directory up is the nearest ENCLOSING target, not the only possible one.
182+
expect(entries[0]!.target).toBe(project.id)
183+
}).pipe(Effect.provide(testLayer(tmp.path))).pipe(Effect.orDie)
184+
}),
185+
),
186+
)
187+
188+
// Delete-the-fix for the fallback branch specifically: without `?? targets.find(kind ===
189+
// "global")`, `findEnclosingTarget` returns undefined here (confirmed red -- neither the
190+
// project nor the "global" test fixture directory encloses a sibling tmpdir), silently
191+
// reporting "no location" for a source that DOES have an enclosing config, just not a nearby
192+
// one. A directory source registered from outside the project tree entirely (e.g. an absolute
193+
// path in a document's `skills: []` array, config/plugin/skill.ts) has no project-tier target
194+
// above it at all -- global is the only target left that structurally encloses it.
195+
it.live("a directory source outside the project tree entirely falls back to the global target", () =>
196+
withTmp((tmp) =>
197+
Effect.gen(function* () {
198+
const outside = yield* Effect.promise(() => tmpdir())
199+
const skillDir = path.join(outside.path, "skill")
200+
yield* Effect.promise(async () => {
201+
await fs.mkdir(path.join(skillDir, "deploy"), { recursive: true })
202+
await write(skillDir, "deploy", "Deploy")
203+
await fs.writeFile(path.join(tmp.path, "opencode.json"), "{}")
204+
})
205+
206+
return yield* Effect.gen(function* () {
207+
const skills = yield* SkillV2.Service
208+
yield* skills.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(skillDir) }))
209+
210+
const catalog = yield* SkillCatalog.Service
211+
const entries = yield* catalog.list()
212+
213+
const documents = yield* ConfigDocument.Service
214+
const global = (yield* documents.listTargets()).find((target) => target.kind === "global")!
215+
expect(entries[0]!.target).toBe(global.id)
216+
217+
yield* Effect.promise(() => outside[Symbol.asyncDispose]())
218+
}).pipe(Effect.provide(testLayer(tmp.path))).pipe(Effect.orDie)
219+
}),
220+
),
221+
)
222+
223+
it.live("url and embedded sources carry no target -- there is no location to attribute", () =>
224+
withTmp((tmp) =>
225+
Effect.gen(function* () {
226+
return yield* Effect.gen(function* () {
227+
const skills = yield* SkillV2.Service
228+
yield* skills.transform((editor) => {
229+
editor.source({
230+
type: "embedded",
231+
skill: { name: "builtin", location: AbsolutePath.make("/builtin/skill"), content: "# builtin" },
232+
})
233+
})
234+
235+
const catalog = yield* SkillCatalog.Service
236+
const entries = yield* catalog.list()
237+
expect(entries).toHaveLength(1)
238+
expect(entries[0]!.target).toBeUndefined()
239+
}).pipe(Effect.provide(testLayer(tmp.path))).pipe(Effect.orDie)
240+
}),
241+
),
242+
)
243+
})

‎packages/core/test/tool-skill.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ describe("SkillTool", () => {
6262
transform: (_transform) => Effect.die("unused"),
6363
reload: () => Effect.die("unused"),
6464
sources: () => Effect.die("unused"),
65+
entries: () => Effect.die("unused"),
6566
list: () => Effect.succeed(current),
6667
}),
6768
)
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
export * as SkillCatalog from "./skill-catalog"
2+
3+
import { Schema } from "effect"
4+
import { ConfigDocument } from "./config-document"
5+
import { Skill } from "./skill"
6+
7+
export class Entry extends Schema.Class<Entry>("Skill.Catalog.Entry")({
8+
skill: Skill.Info,
9+
source: Skill.Source,
10+
/** Index into this location's registered source list, in registration order -- the same
11+
* ordering `mergeSkills` (packages/core/src/skill.ts) resolves collisions against. Exposed so a
12+
* client can show "this one, not that one" without re-deriving the winner itself. */
13+
sourceIndex: Schema.Int,
14+
/** Present only when a later-registered source declares a skill of the same name -- absent
15+
* means this is the effective (winning) skill `SkillV2.list()` would also return. */
16+
shadowedBy: Schema.Struct({ source: Skill.Source, sourceIndex: Schema.Int }).pipe(Schema.optional),
17+
/** The config-document target that encloses this skill's declaring location, so a client can
18+
* jump straight to editing it -- present for a `directory` source whose path falls under a
19+
* known target's directory (global or a discovered project tier), walking up to the nearest
20+
* enclosing one when the exact directory has no config file of its own (e.g. a bare `.opencode`
21+
* tier). Absent for `url` and `embedded` sources, which have no location to attribute at all. */
22+
target: ConfigDocument.TargetID.pipe(Schema.optional),
23+
}) {}

0 commit comments

Comments
 (0)