@srobroek/harness-kit 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/config.ts ADDED
@@ -0,0 +1,150 @@
1
+ // The per-repo settings in harness-kit.json. Everything the generator used to hold as a constant lives here.
2
+
3
+ import { existsSync, readFileSync } from "node:fs"
4
+ import path from "node:path"
5
+ import { fail, isRecord, nonEmptyString } from "./util"
6
+
7
+ export const CONFIG_FILE = "harness-kit.json"
8
+
9
+ /** Every harness the generator can target, in the canonical order used for output. */
10
+ export const KNOWN_HARNESSES = ["opencode", "claude", "omp"] as const
11
+ export type Harness = (typeof KNOWN_HARNESSES)[number]
12
+
13
+ /** Every inventory kind the generator can report, in canonical order. */
14
+ export const KNOWN_KINDS = ["skills", "agents", "commands", "rules", "templates", "styles", "hooks", "tools", "extensions", "mcp"] as const
15
+ export type Kind = (typeof KNOWN_KINDS)[number]
16
+
17
+ export type Config = {
18
+ marketplace: { name: string; description: string; owner: { name: string } }
19
+ harnesses: Harness[]
20
+ /** Directories under plugins/<name>/common/ that are copied into each harness tree. */
21
+ commonDirs: string[]
22
+ kinds: Kind[]
23
+ /** Key in plugins/<name>/package.json that holds the plugin's own settings. */
24
+ pluginKey: string
25
+ /** npm scope of the generated OMP package name. */
26
+ ompScope: string
27
+ /** Names the generator in the note at the top of generated Markdown files. */
28
+ generatedBy: string
29
+ claude: {
30
+ /** `harness-kit validate-claude` runs `claude plugin validate --strict` when true. */
31
+ strict: boolean
32
+ /** Written to a Claude manifest whose package.json sets no author. */
33
+ author?: { name: string }
34
+ /** Written to a Claude manifest whose package.json sets no license. */
35
+ license?: string
36
+ }
37
+ omp: { packageType?: "module" | "commonjs" }
38
+ }
39
+
40
+ const TOP_KEYS = ["marketplace", "harnesses", "commonDirs", "kinds", "pluginKey", "ompScope", "generatedBy", "claude", "omp"]
41
+ const DIR_NAME = /^[a-z0-9][a-z0-9._-]*$/
42
+ const PACKAGE_SCOPE = /^@[a-z0-9][a-z0-9._-]*$/
43
+
44
+ const DEFAULT_KINDS: Kind[] = ["skills", "agents", "commands", "rules", "hooks", "tools", "extensions", "mcp"]
45
+
46
+ function onlyKeys(where: string, field: string, value: Record<string, unknown>, allowed: string[]): void {
47
+ const unknown = Object.keys(value).filter((key) => !allowed.includes(key))
48
+ if (unknown.length > 0) fail(where, `unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${field}${k}"`).join(", ")} (allowed: ${allowed.join(", ")})`)
49
+ }
50
+
51
+ /** A list of unique strings drawn from `allowed` (when given), returned in the order of `allowed`. */
52
+ function pickList<T extends string>(where: string, field: string, noun: string, raw: unknown, allowed: readonly T[]): T[] {
53
+ if (!Array.isArray(raw) || raw.length === 0) fail(where, `"${field}" must be a non-empty array (use ${allowed.join(", ")})`)
54
+ for (const item of raw) {
55
+ if (!(allowed as readonly unknown[]).includes(item)) fail(where, `unknown ${noun} "${String(item)}" in "${field}" (use ${allowed.join(", ")})`)
56
+ }
57
+ if (new Set(raw).size !== raw.length) fail(where, `"${field}" lists a value twice`)
58
+ return allowed.filter((item) => raw.includes(item))
59
+ }
60
+
61
+ /** Validate a parsed harness-kit.json and fill in defaults. `where` names the file in error messages. */
62
+ export function resolveConfig(raw: unknown, where = CONFIG_FILE): Config {
63
+ if (!isRecord(raw)) fail(where, "must be a JSON object")
64
+ onlyKeys(where, "", raw, TOP_KEYS)
65
+
66
+ const market = raw.marketplace
67
+ if (!isRecord(market)) fail(where, 'missing "marketplace" object ({ name, description, owner: { name } })')
68
+ onlyKeys(where, "marketplace.", market, ["name", "description", "owner"])
69
+ const name = nonEmptyString(where, "marketplace.name", market.name)
70
+ const description = nonEmptyString(where, "marketplace.description", market.description)
71
+ if (!isRecord(market.owner)) fail(where, '"marketplace.owner" must be an object with a name')
72
+ const owner = { name: nonEmptyString(where, "marketplace.owner.name", market.owner.name) }
73
+
74
+ const harnesses = raw.harnesses === undefined ? [...KNOWN_HARNESSES] : pickList(where, "harnesses", "harness", raw.harnesses, KNOWN_HARNESSES)
75
+
76
+ let commonDirs = ["skills", "rules"]
77
+ if (raw.commonDirs !== undefined) {
78
+ if (!Array.isArray(raw.commonDirs) || raw.commonDirs.length === 0) fail(where, '"commonDirs" must be a non-empty array of directory names')
79
+ for (const dir of raw.commonDirs) {
80
+ if (typeof dir !== "string" || !DIR_NAME.test(dir)) fail(where, `"commonDirs" entry ${JSON.stringify(dir)} must be a plain directory name`)
81
+ }
82
+ if (new Set(raw.commonDirs).size !== raw.commonDirs.length) fail(where, '"commonDirs" lists a directory twice')
83
+ commonDirs = raw.commonDirs as string[]
84
+ }
85
+
86
+ const kinds = raw.kinds === undefined ? DEFAULT_KINDS : pickList(where, "kinds", "kind", raw.kinds, KNOWN_KINDS)
87
+
88
+ const pluginKey = raw.pluginKey === undefined ? "agent-plugins" : nonEmptyString(where, "pluginKey", raw.pluginKey)
89
+ const ompScope = raw.ompScope === undefined ? "@agent-plugins" : nonEmptyString(where, "ompScope", raw.ompScope)
90
+ if (!PACKAGE_SCOPE.test(ompScope)) fail(where, `"ompScope" must look like "@scope", got "${ompScope}"`)
91
+ const generatedBy = raw.generatedBy === undefined ? "harness-kit build" : nonEmptyString(where, "generatedBy", raw.generatedBy)
92
+
93
+ const claude: Config["claude"] = { strict: true }
94
+ if (raw.claude !== undefined) {
95
+ if (!isRecord(raw.claude)) fail(where, '"claude" must be an object')
96
+ onlyKeys(where, "claude.", raw.claude, ["strict", "author", "license"])
97
+ if (raw.claude.strict !== undefined) {
98
+ if (typeof raw.claude.strict !== "boolean") fail(where, '"claude.strict" must be true or false')
99
+ claude.strict = raw.claude.strict
100
+ }
101
+ if (raw.claude.author !== undefined) {
102
+ if (!isRecord(raw.claude.author)) fail(where, '"claude.author" must be an object with a name')
103
+ claude.author = { name: nonEmptyString(where, "claude.author.name", raw.claude.author.name) }
104
+ }
105
+ if (raw.claude.license !== undefined) claude.license = nonEmptyString(where, "claude.license", raw.claude.license)
106
+ }
107
+
108
+ const omp: Config["omp"] = {}
109
+ if (raw.omp !== undefined) {
110
+ if (!isRecord(raw.omp)) fail(where, '"omp" must be an object')
111
+ onlyKeys(where, "omp.", raw.omp, ["packageType"])
112
+ if (raw.omp.packageType !== undefined) {
113
+ if (raw.omp.packageType !== "module" && raw.omp.packageType !== "commonjs") fail(where, '"omp.packageType" must be "module" or "commonjs"')
114
+ omp.packageType = raw.omp.packageType
115
+ }
116
+ }
117
+
118
+ return {
119
+ marketplace: { name, description, owner },
120
+ harnesses,
121
+ commonDirs,
122
+ kinds,
123
+ pluginKey,
124
+ ompScope,
125
+ generatedBy,
126
+ claude,
127
+ omp,
128
+ }
129
+ }
130
+
131
+ /** Read and validate <root>/harness-kit.json. */
132
+ export function loadConfig(root: string): Config {
133
+ const file = path.join(root, CONFIG_FILE)
134
+ if (!existsSync(file)) fail(CONFIG_FILE, `not found in ${root}; create it (see the README, "Config")`)
135
+ let raw: unknown
136
+ try {
137
+ raw = JSON.parse(readFileSync(file, "utf8"))
138
+ } catch (error) {
139
+ fail(CONFIG_FILE, `is not valid JSON (${error instanceof Error ? error.message : String(error)})`)
140
+ }
141
+ return resolveConfig(raw)
142
+ }
143
+
144
+ /** The nearest directory at or above `start` that holds a harness-kit.json. */
145
+ export function findRoot(start: string): string | undefined {
146
+ for (let dir = path.resolve(start); ; dir = path.dirname(dir)) {
147
+ if (existsSync(path.join(dir, CONFIG_FILE))) return dir
148
+ if (path.dirname(dir) === dir) return undefined
149
+ }
150
+ }
@@ -0,0 +1,520 @@
1
+ // Generates every derived file in the repository from plugins/<name>/package.json and
2
+ // plugins/<name>/common/, following the repo's harness-kit.json. The CLI lives in cli.ts; this
3
+ // module holds the logic so tests can drive it against a fixture tree.
4
+
5
+ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
6
+ import path from "node:path"
7
+ import { type Config, type Harness, KNOWN_HARNESSES, KNOWN_KINDS, type Kind } from "./config"
8
+ import { fail, isRecord, json, nonEmptyString } from "./util"
9
+
10
+ export type { Harness, Kind }
11
+ export type HarnessInventory = Record<Kind, string[]>
12
+
13
+ /** A user-facing option. Every harness exposes it its own way; the default is a string. */
14
+ export type PluginOption = { description: string; default: string }
15
+
16
+ export type Plugin = {
17
+ name: string
18
+ version: string
19
+ description: string
20
+ category: string
21
+ harnesses: Harness[]
22
+ scope?: string
23
+ /** One line on how the harness builds differ. */
24
+ discrepancies?: string
25
+ /** Options the plugin's templates take, by name. A name is letters, digits and underscores. Exclusive with `userConfig`. */
26
+ options?: Record<string, PluginOption>
27
+ /** Name of the Claude plugin when it differs from the directory name; it sets the `/<name>:<command>` namespace. */
28
+ claudeName?: string
29
+ /** Author and license go into the Claude manifest, which strict validation requires. */
30
+ author?: { name: string }
31
+ license?: string
32
+ /** The Claude `userConfig` schema, copied into plugin.json as is. Exclusive with `options`. */
33
+ userConfig?: Record<string, unknown>
34
+ }
35
+
36
+ export type Output = { file: string; contents: string | Buffer }
37
+ export type Drift = { changed: string[]; extra: string[] }
38
+
39
+ const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/
40
+ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
41
+ const OPTION_NAME = /^[a-z][a-z0-9_]*$/
42
+ const OPENCODE_SDK_RANGE = ">=2.1.4 <3"
43
+ const MODULE_EXTENSION = /\.(?:[cm]?[jt]s)$/
44
+
45
+ const generatedNote = (config: Config) => `<!-- Generated by ${config.generatedBy}. Do not edit. -->`
46
+
47
+ export function assertSemver(version: string): void {
48
+ if (!SEMVER.test(version)) throw new Error(`"${version}" is not a semver version (expected x.y.z)`)
49
+ }
50
+
51
+ function listDirs(dir: string): string[] {
52
+ if (!existsSync(dir)) return []
53
+ return readdirSync(dir, { withFileTypes: true })
54
+ .filter((entry) => entry.isDirectory())
55
+ .map((entry) => entry.name)
56
+ .sort()
57
+ }
58
+
59
+ /** Files under dir as sorted posix-style paths relative to it. */
60
+ function listFiles(dir: string): string[] {
61
+ if (!existsSync(dir)) return []
62
+ const found: string[] = []
63
+ const walk = (current: string, prefix: string) => {
64
+ for (const entry of readdirSync(current, { withFileTypes: true })) {
65
+ // Bytecode caches that a test or a run leaves behind are not content.
66
+ if (entry.name === "__pycache__") continue
67
+ const relative = prefix ? `${prefix}/${entry.name}` : entry.name
68
+ if (entry.isDirectory()) walk(path.join(current, entry.name), relative)
69
+ else found.push(relative)
70
+ }
71
+ }
72
+ walk(dir, "")
73
+ return found.sort()
74
+ }
75
+
76
+ const stripExtension = (file: string) => file.replace(/\.[^./]+$/, "")
77
+
78
+ export function readPlugin(root: string, name: string, config: Config): Plugin {
79
+ const key = config.pluginKey
80
+ const where = `plugins/${name}/package.json`
81
+ const file = path.join(root, "plugins", name, "package.json")
82
+ if (!existsSync(file)) fail(where, "missing")
83
+ const manifest = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>
84
+ if (manifest.name !== name) fail(where, `name "${String(manifest.name)}" must equal the directory name "${name}"`)
85
+ if (!NAME_PATTERN.test(name)) fail(where, `"${name}" is not a valid plugin name`)
86
+ const version = manifest.version
87
+ if (typeof version !== "string" || !SEMVER.test(version)) fail(where, `version "${String(version)}" is not semver`)
88
+ const own = manifest[key]
89
+ if (!isRecord(own)) fail(where, `missing "${key}" key`)
90
+ const description = nonEmptyString(where, `${key}.description`, own.description)
91
+ const category = nonEmptyString(where, `${key}.category`, own.category)
92
+ const harnesses = own.harnesses
93
+ if (!Array.isArray(harnesses) || harnesses.length === 0) fail(where, "harnesses must list at least one harness")
94
+ for (const harness of harnesses) {
95
+ if (!(KNOWN_HARNESSES as readonly unknown[]).includes(harness)) {
96
+ fail(where, `unknown harness "${String(harness)}" (use ${KNOWN_HARNESSES.join(", ")})`)
97
+ }
98
+ if (!(config.harnesses as readonly unknown[]).includes(harness)) {
99
+ fail(where, `harness "${String(harness)}" is not enabled in harness-kit.json (enabled: ${config.harnesses.join(", ")})`)
100
+ }
101
+ }
102
+ const scope = own.scope === undefined ? undefined : nonEmptyString(where, `${key}.scope`, own.scope)
103
+ for (const harness of KNOWN_HARNESSES) {
104
+ if (!harnesses.includes(harness) && existsSync(path.join(root, "plugins", name, harness))) {
105
+ fail(`plugins/${name}/${harness}`, `exists but "${harness}" is not in harnesses`)
106
+ }
107
+ }
108
+ const discrepancies = own.discrepancies === undefined ? undefined : nonEmptyString(where, `${key}.discrepancies`, own.discrepancies)
109
+ if (discrepancies !== undefined && /[\r\n]/.test(discrepancies)) fail(where, `"${key}.discrepancies" must be one line`)
110
+ const options = readOptions(where, key, own.options)
111
+ let claudeName: string | undefined
112
+ if (own.claudeName !== undefined) {
113
+ claudeName = nonEmptyString(where, `${key}.claudeName`, own.claudeName)
114
+ if (!NAME_PATTERN.test(claudeName)) fail(where, `"${key}.claudeName" must be kebab-case`)
115
+ }
116
+ let author: { name: string } | undefined
117
+ if (manifest.author !== undefined) {
118
+ const raw = manifest.author
119
+ const authorName = typeof raw === "string" ? raw : isRecord(raw) ? raw.name : undefined
120
+ if (typeof authorName !== "string" || !authorName.trim()) fail(where, '"author" must be a string or an object with a name')
121
+ author = { name: authorName }
122
+ }
123
+ const license = manifest.license === undefined ? undefined : nonEmptyString(where, "license", manifest.license)
124
+ if (own.userConfig !== undefined && !isRecord(own.userConfig)) fail(where, `"${key}.userConfig" must be an object`)
125
+ const userConfig = own.userConfig as Record<string, unknown> | undefined
126
+ if (options && userConfig) fail(where, `set either "${key}.options" or "${key}.userConfig", not both: options generate the userConfig`)
127
+ // Keep canonical harness order so output does not depend on how the author ordered the list.
128
+ return {
129
+ name,
130
+ version,
131
+ description,
132
+ category,
133
+ harnesses: KNOWN_HARNESSES.filter((h) => harnesses.includes(h)),
134
+ scope,
135
+ discrepancies,
136
+ options,
137
+ claudeName,
138
+ author,
139
+ license,
140
+ userConfig,
141
+ }
142
+ }
143
+
144
+ function readOptions(where: string, key: string, raw: unknown): Record<string, PluginOption> | undefined {
145
+ if (raw === undefined) return undefined
146
+ if (!isRecord(raw)) fail(where, `"${key}.options" must be an object`)
147
+ const options: Record<string, PluginOption> = {}
148
+ for (const [name, value] of Object.entries(raw)) {
149
+ if (!OPTION_NAME.test(name)) fail(where, `option "${name}" must be lowercase letters, digits and underscores`)
150
+ if (!isRecord(value)) fail(where, `option "${name}" must be an object`)
151
+ const description = nonEmptyString(where, `option "${name}" description`, value.description)
152
+ if (typeof value.default !== "string") fail(where, `option "${name}" needs a string "default"`)
153
+ options[name] = { description, default: value.default }
154
+ }
155
+ return options
156
+ }
157
+
158
+ /** Bare specifiers (neither relative nor `node:`) imported or re-exported by a module's source text. */
159
+ export function bareImports(source: string): string[] {
160
+ const found: string[] = []
161
+ const pattern = /(?:^|[;\n])\s*(?:(?:import|export)\b[^"'`;]*?\bfrom\s*|import\s*)["']([^"']+)["']/g
162
+ for (const match of source.matchAll(pattern)) {
163
+ const specifier = match[1] as string
164
+ if (!specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.startsWith("node:")) found.push(specifier)
165
+ }
166
+ return found
167
+ }
168
+
169
+ /**
170
+ * OpenCode resolves host-provided packages (the plugin SDK, OpenTUI, Solid) only for modules reached through an import.
171
+ * The files it loads first, the targets of the OpenCode package `exports`, must therefore import nothing bare.
172
+ */
173
+ function checkOpencodeEntries(root: string, plugin: Plugin): void {
174
+ if (!plugin.harnesses.includes("opencode")) return
175
+ const dir = harnessDir(root, plugin, "opencode")
176
+ for (const target of Object.values(opencodeExports(root, plugin))) {
177
+ const file = path.join(dir, target)
178
+ if (!existsSync(file)) continue
179
+ const bare = bareImports(readFileSync(file, "utf8"))
180
+ if (bare.length > 0) {
181
+ fail(`plugins/${plugin.name}/opencode/${target.replace("./", "")}`, `entry file imports ${bare.map((x) => `"${x}"`).join(", ")} directly; move it behind a shim (the entry re-exports from another module)`)
182
+ }
183
+ }
184
+ }
185
+
186
+ export function readPlugins(root: string, config: Config): Plugin[] {
187
+ const plugins = listDirs(path.join(root, "plugins")).map((name) => readPlugin(root, name, config))
188
+ for (const plugin of plugins) checkOpencodeEntries(root, plugin)
189
+ return plugins
190
+ }
191
+
192
+ const pluginDir = (root: string, plugin: Plugin) => path.join(root, "plugins", plugin.name)
193
+ const harnessDir = (root: string, plugin: Plugin, harness: Harness) => path.join(pluginDir(root, plugin), harness)
194
+
195
+ /** Matches `<name>.<harness>.<ext>`: a copy of `<name>.<ext>` that only that harness gets. */
196
+ const VARIANT = new RegExp(`^(.+)\\.(${KNOWN_HARNESSES.join("|")})(\\.[^./]+)$`)
197
+
198
+ /** OMP injects a plugin rule into the system prompt only when its front matter says `alwaysApply: true`. */
199
+ const OMP_ALWAYS_APPLY = "---\nalwaysApply: true\n---\n\n"
200
+
201
+ /**
202
+ * The common files one harness receives, as [source, destination] pairs relative to common/<dir>.
203
+ * `x.<harness>.md` replaces `x.md` in that harness and appears in no other.
204
+ */
205
+ function commonFilesFor(files: string[], harness: Harness): Array<[string, string]> {
206
+ const variantOf = (file: string) => {
207
+ const match = VARIANT.exec(path.basename(file))
208
+ return match ? { harness: match[2], plain: path.join(path.dirname(file), `${match[1]}${match[3]}`) } : undefined
209
+ }
210
+ const overridden = new Set(files.flatMap((file) => (variantOf(file)?.harness === harness ? [variantOf(file)!.plain] : [])))
211
+ const picked: Array<[string, string]> = []
212
+ for (const file of files) {
213
+ const variant = variantOf(file)
214
+ if (!variant) {
215
+ if (!overridden.has(file)) picked.push([file, file])
216
+ } else if (variant.harness === harness) picked.push([file, variant.plain])
217
+ }
218
+ return picked
219
+ }
220
+
221
+ function ownedCopies(root: string, plugin: Plugin, config: Config): Output[] {
222
+ const common = path.join(pluginDir(root, plugin), "common")
223
+ const outputs: Output[] = []
224
+ for (const harness of plugin.harnesses) {
225
+ for (const dir of config.commonDirs) {
226
+ for (const [source, dest] of commonFilesFor(listFiles(path.join(common, dir)), harness)) {
227
+ let contents: string | Buffer = readFileSync(path.join(common, dir, source))
228
+ if (harness === "omp" && dir === "rules" && !contents.subarray(0, 3).equals(Buffer.from("---"))) {
229
+ contents = OMP_ALWAYS_APPLY + contents.toString("utf8")
230
+ }
231
+ outputs.push({ file: path.join(harnessDir(root, plugin, harness), dir, dest), contents })
232
+ }
233
+ }
234
+ }
235
+ return outputs
236
+ }
237
+
238
+ function ompExtensions(root: string, plugin: Plugin): string[] {
239
+ const dir = path.join(harnessDir(root, plugin, "omp"), "extensions")
240
+ if (!existsSync(dir)) return []
241
+ return readdirSync(dir, { withFileTypes: true })
242
+ .filter((entry) => entry.isFile() && MODULE_EXTENSION.test(entry.name))
243
+ .map((entry) => `./extensions/${entry.name}`)
244
+ .sort()
245
+ }
246
+
247
+ function opencodeFile(root: string, plugin: Plugin, base: "index" | "tui"): string | undefined {
248
+ const dir = harnessDir(root, plugin, "opencode")
249
+ return [`${base}.ts`, `${base}.js`].find((file) => existsSync(path.join(dir, file)))
250
+ }
251
+
252
+ /** The `exports` map of the OpenCode package: the server entry, plus `./tui` when the tree has a TUI half. */
253
+ function opencodeExports(root: string, plugin: Plugin): Record<string, string> {
254
+ const tui = opencodeFile(root, plugin, "tui")
255
+ return { ".": `./${opencodeFile(root, plugin, "index") ?? "index.js"}`, ...(tui ? { "./tui": `./${tui}` } : {}) }
256
+ }
257
+
258
+ function claudeUserConfig(options: Record<string, PluginOption>) {
259
+ return Object.fromEntries(
260
+ Object.entries(options).map(([name, option]) => [
261
+ name,
262
+ { type: "string", title: name, description: option.description, default: option.default },
263
+ ]),
264
+ )
265
+ }
266
+
267
+ /** The defaults of the plugin's options, read at run time by every harness build. */
268
+ function optionDefaults(root: string, plugin: Plugin): Output[] {
269
+ if (!plugin.options) return []
270
+ const defaults = Object.fromEntries(Object.entries(plugin.options).map(([name, option]) => [name, option.default]))
271
+ return plugin.harnesses.map((harness) => ({ file: path.join(harnessDir(root, plugin, harness), "options.json"), contents: json(defaults) }))
272
+ }
273
+
274
+ function manifests(root: string, plugin: Plugin, config: Config): Output[] {
275
+ const { name, version, description, category } = plugin
276
+ const outputs: Output[] = []
277
+ const at = (harness: Harness, file: string) => path.join(harnessDir(root, plugin, harness), file)
278
+ if (plugin.harnesses.includes("claude")) {
279
+ const author = plugin.author ?? config.claude.author
280
+ const license = plugin.license ?? config.claude.license
281
+ const userConfig = plugin.userConfig ?? (plugin.options ? claudeUserConfig(plugin.options) : undefined)
282
+ outputs.push({
283
+ file: at("claude", ".claude-plugin/plugin.json"),
284
+ contents: json({
285
+ name: plugin.claudeName ?? name,
286
+ description,
287
+ version,
288
+ ...(author ? { author } : {}),
289
+ ...(license ? { license } : {}),
290
+ ...(userConfig ? { userConfig } : {}),
291
+ }),
292
+ })
293
+ }
294
+ if (plugin.harnesses.includes("omp")) {
295
+ outputs.push({
296
+ file: at("omp", "package.json"),
297
+ contents: json({
298
+ name: `${config.ompScope}/${name}`,
299
+ version,
300
+ description,
301
+ private: true,
302
+ ...(config.omp.packageType ? { type: config.omp.packageType } : {}),
303
+ omp: ompExtensions(root, plugin).length > 0 ? { extensions: ompExtensions(root, plugin) } : {},
304
+ }),
305
+ })
306
+ outputs.push({ file: at("omp", ".omp-plugin/plugin.json"), contents: json({ name, description, version, category }) })
307
+ }
308
+ if (plugin.harnesses.includes("opencode")) {
309
+ outputs.push({
310
+ file: at("opencode", "package.json"),
311
+ contents: json({
312
+ name: `${name}-opencode`,
313
+ version,
314
+ private: true,
315
+ type: "module",
316
+ exports: opencodeExports(root, plugin),
317
+ peerDependencies: { "@opencode/plugin": OPENCODE_SDK_RANGE },
318
+ peerDependenciesMeta: { "@opencode/plugin": { optional: true } },
319
+ }),
320
+ })
321
+ }
322
+ return outputs
323
+ }
324
+
325
+ function readJsonFile(file: string): unknown {
326
+ return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : undefined
327
+ }
328
+
329
+ /** What one harness tree ships. `generated` holds the paths (relative to the tree) this run copies in. */
330
+ function inventoryOf(root: string, plugin: Plugin, harness: Harness, generated: string[], config: Config): HarnessInventory {
331
+ const dir = harnessDir(root, plugin, harness)
332
+ const own = listFiles(dir).filter((file) => !config.commonDirs.some((common) => file.startsWith(`${common}/`)))
333
+ const files = [...new Set([...own, ...generated])].sort()
334
+ const names = (prefix: string, accept: (rest: string) => boolean = () => true) =>
335
+ files
336
+ .filter((file) => file.startsWith(`${prefix}/`) && accept(file.slice(prefix.length + 1)))
337
+ .map((file) => file.slice(prefix.length + 1))
338
+
339
+ const skills = names("skills", (rest) => rest.endsWith("/SKILL.md")).map((rest) => rest.split("/")[0]!)
340
+ const agents = names("agents", (rest) => rest.endsWith(".md") && !rest.includes("/")).map(stripExtension)
341
+ const commands = names("commands", (rest) => rest.endsWith(".md")).map(stripExtension)
342
+ const rules = names("rules", (rest) => /\.mdc?$/.test(rest)).map(stripExtension)
343
+ const templates = names("templates", (rest) => /\.md$/.test(rest)).map(stripExtension)
344
+ const styles = harness === "claude" ? names("output-styles", (rest) => rest.endsWith(".md") && !rest.includes("/")).map(stripExtension) : []
345
+
346
+ const hooks: string[] = []
347
+ if (harness === "claude") {
348
+ const hooksConfig = readJsonFile(path.join(dir, "hooks", "hooks.json"))
349
+ const events = isRecord(hooksConfig) && isRecord(hooksConfig.hooks) ? Object.keys(hooksConfig.hooks) : []
350
+ hooks.push(...events)
351
+ }
352
+ if (harness === "omp") {
353
+ for (const phase of ["pre", "post"]) hooks.push(...names(`hooks/${phase}`).map((rest) => `${phase}/${stripExtension(rest)}`))
354
+ }
355
+
356
+ const tools = names("tools").map((rest) => stripExtension(rest.split("/")[0]!))
357
+ const extensions =
358
+ harness === "opencode"
359
+ ? files.filter((file) => /^(?:index|tui)\.[cm]?[jt]s$/.test(file)).map(stripExtension)
360
+ : harness === "omp"
361
+ ? names("extensions", (rest) => MODULE_EXTENSION.test(rest) && !rest.includes("/")).map(stripExtension)
362
+ : []
363
+
364
+ const mcpConfig = readJsonFile(path.join(dir, ".mcp.json"))
365
+ const mcp = isRecord(mcpConfig) ? Object.keys(isRecord(mcpConfig.mcpServers) ? mcpConfig.mcpServers : mcpConfig) : []
366
+
367
+ const unique = (list: string[]) => [...new Set(list)].sort()
368
+ const found: HarnessInventory = {
369
+ skills: unique(skills),
370
+ agents: unique(agents),
371
+ commands: unique(commands),
372
+ rules: unique(rules),
373
+ templates: unique(templates),
374
+ styles: unique(styles),
375
+ hooks: unique(hooks),
376
+ tools: unique(tools),
377
+ extensions: unique(extensions),
378
+ mcp: unique(mcp),
379
+ }
380
+ // Only the kinds the repo enables appear, in canonical order.
381
+ return Object.fromEntries(KNOWN_KINDS.filter((kind) => config.kinds.includes(kind)).map((kind) => [kind, found[kind]])) as HarnessInventory
382
+ }
383
+
384
+ type PluginInventory = Plugin & { harnesses: Harness[]; contents: Partial<Record<Harness, HarnessInventory>> }
385
+
386
+ function buildInventory(root: string, plugin: Plugin, copies: Output[], config: Config): PluginInventory {
387
+ const contents: Partial<Record<Harness, HarnessInventory>> = {}
388
+ for (const harness of plugin.harnesses) {
389
+ const prefix = harnessDir(root, plugin, harness) + path.sep
390
+ const generated = copies
391
+ .filter((copy) => copy.file.startsWith(prefix))
392
+ .map((copy) => copy.file.slice(prefix.length).split(path.sep).join("/"))
393
+ contents[harness] = inventoryOf(root, plugin, harness, generated, config)
394
+ }
395
+ return { ...plugin, contents }
396
+ }
397
+
398
+ const cell = (names: string[]) => (names.length > 0 ? names.join(", ") : "-")
399
+
400
+ function pluginInventoryMarkdown(entry: PluginInventory, config: Config): string {
401
+ const header = `| Kind | ${entry.harnesses.join(" | ")} |`
402
+ const divider = `| --- |${entry.harnesses.map(() => " --- |").join("")}`
403
+ const rows = config.kinds.map((kind) => `| ${kind} | ${entry.harnesses.map((h) => cell(entry.contents[h]![kind])).join(" | ")} |`)
404
+ return [generatedNote(config), `# ${entry.name}`, "", entry.description, "", header, divider, ...rows, ""].join("\n")
405
+ }
406
+
407
+ function rootInventoryMarkdown(entries: PluginInventory[], config: Config): string {
408
+ const lines = [generatedNote(config), "# Inventory", ""]
409
+ if (entries.length === 0) {
410
+ lines.push("No plugins yet.", "")
411
+ return lines.join("\n")
412
+ }
413
+ lines.push("| Plugin | Version | Category | Scope | Harnesses |", "| --- | --- | --- | --- | --- |")
414
+ for (const entry of entries) {
415
+ lines.push(`| ${entry.name} | ${entry.version} | ${entry.category} | ${entry.scope ?? "-"} | ${entry.harnesses.join(", ")} |`)
416
+ }
417
+ lines.push("", "Each plugin's own `INVENTORY.md` lists what it ships per harness.", "")
418
+ const notes = entries.filter((entry) => entry.discrepancies)
419
+ if (notes.length > 0) {
420
+ lines.push("## Harness discrepancies", "")
421
+ for (const entry of notes) lines.push(`- ${entry.name}: ${entry.discrepancies}`)
422
+ lines.push("")
423
+ }
424
+ return lines.join("\n")
425
+ }
426
+
427
+ /** Harnesses that read a marketplace file, with the directory that holds it. */
428
+ const MARKETPLACE_DIRS = { claude: ".claude-plugin", omp: ".omp-plugin" } as const
429
+
430
+ function marketplace(plugins: Plugin[], harness: keyof typeof MARKETPLACE_DIRS, config: Config) {
431
+ return {
432
+ $schema: "https://anthropic.com/claude-code/marketplace.schema.json",
433
+ name: config.marketplace.name,
434
+ owner: config.marketplace.owner,
435
+ metadata: { description: config.marketplace.description },
436
+ plugins: plugins
437
+ .filter((plugin) => plugin.harnesses.includes(harness))
438
+ .map((plugin) => ({
439
+ name: harness === "claude" ? (plugin.claudeName ?? plugin.name) : plugin.name,
440
+ description: plugin.description,
441
+ source: `./plugins/${plugin.name}/${harness}`,
442
+ version: plugin.version,
443
+ category: plugin.category,
444
+ })),
445
+ }
446
+ }
447
+
448
+ /** Every generated file for the given plugins. */
449
+ export function render(root: string, plugins: Plugin[], config: Config): Output[] {
450
+ const outputs: Output[] = (Object.keys(MARKETPLACE_DIRS) as Array<keyof typeof MARKETPLACE_DIRS>)
451
+ .filter((harness) => config.harnesses.includes(harness))
452
+ .map((harness) => ({
453
+ file: path.join(root, MARKETPLACE_DIRS[harness], "marketplace.json"),
454
+ contents: json(marketplace(plugins, harness, config)),
455
+ }))
456
+ const entries: PluginInventory[] = []
457
+ for (const plugin of plugins) {
458
+ const copies = ownedCopies(root, plugin, config)
459
+ const entry = buildInventory(root, plugin, copies, config)
460
+ entries.push(entry)
461
+ outputs.push(...manifests(root, plugin, config), ...optionDefaults(root, plugin), ...copies)
462
+ outputs.push({ file: path.join(pluginDir(root, plugin), "INVENTORY.md"), contents: pluginInventoryMarkdown(entry, config) })
463
+ }
464
+ outputs.push({ file: path.join(root, "INVENTORY.md"), contents: rootInventoryMarkdown(entries, config) })
465
+ outputs.push({
466
+ file: path.join(root, "inventory.json"),
467
+ contents: json({
468
+ plugins: entries.map(({ contents, author, license, userConfig, ...plugin }) => ({ ...plugin, harnesses: contents })),
469
+ }),
470
+ })
471
+ return outputs
472
+ }
473
+
474
+ /** Files in common-owned directories of a listed harness tree. Any not in a fresh render is stale. */
475
+ function ownedFiles(root: string, plugins: Plugin[], config: Config): string[] {
476
+ return plugins.flatMap((plugin) =>
477
+ plugin.harnesses.flatMap((harness) =>
478
+ config.commonDirs.flatMap((dir) => {
479
+ const base = path.join(harnessDir(root, plugin, harness), dir)
480
+ return listFiles(base).map((file) => path.join(base, file))
481
+ }),
482
+ ),
483
+ )
484
+ }
485
+
486
+ export function drift(root: string, outputs: readonly Output[], config: Config): Drift {
487
+ const expected = new Set(outputs.map((output) => output.file))
488
+ const changed = outputs
489
+ .filter((output) => {
490
+ if (!existsSync(output.file)) return true
491
+ return !Buffer.from(output.contents).equals(readFileSync(output.file))
492
+ })
493
+ .map((output) => output.file)
494
+ const extra = ownedFiles(root, readPlugins(root, config), config).filter((file) => !expected.has(file))
495
+ return { changed, extra }
496
+ }
497
+
498
+ export function write(root: string, outputs: readonly Output[], config: Config): void {
499
+ for (const file of drift(root, outputs, config).extra) {
500
+ rmSync(file)
501
+ for (let dir = path.dirname(file); readdirSync(dir).length === 0; dir = path.dirname(dir)) rmSync(dir, { recursive: true })
502
+ }
503
+ for (const output of outputs) {
504
+ mkdirSync(path.dirname(output.file), { recursive: true })
505
+ writeFileSync(output.file, output.contents)
506
+ }
507
+ }
508
+
509
+ /** Set a plugin's version in package.json, then regenerate everything derived from it. */
510
+ export function stampVersion(root: string, name: string, version: string, config: Config): void {
511
+ assertSemver(version)
512
+ const plugins = readPlugins(root, config)
513
+ if (!plugins.some((plugin) => plugin.name === name)) throw new Error(`unknown plugin "${name}"`)
514
+ const file = path.join(root, "plugins", name, "package.json")
515
+ const manifest = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>
516
+ manifest.version = version
517
+ writeFileSync(file, json(manifest))
518
+ const fresh = readPlugins(root, config)
519
+ write(root, render(root, fresh, config), config)
520
+ }