@srobroek/harness-kit 0.0.0-stage → 1.0.1
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/LICENSE +202 -0
- package/README.md +162 -2
- package/package.json +84 -4
- package/release.config.js +41 -0
- package/src/cli.ts +135 -0
- package/src/config.ts +150 -0
- package/src/generate.ts +520 -0
- package/src/index.ts +20 -0
- package/src/update.ts +68 -0
- package/src/util.ts +15 -0
- package/src/validate-claude.ts +53 -0
- package/src/workflow-refs.ts +34 -0
- package/tsconfig.base.json +14 -0
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
|
+
}
|
package/src/generate.ts
ADDED
|
@@ -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
|
+
}
|