Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(ruflo-plugin-creator): function-hook mod (ADR-445)

ruv53563c63aeda
diff --git a/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json b/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json
index dcc382b892..c82aed086f 100644
--- a/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json
+++ b/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-plugin-creator",
- "description": "Scaffold, validate, and publish new Claude Code plugins with the canonical plugin contract — now including governed Claude Code mods (function hooks), ADR + smoke + Compatibility + namespace coordination + MCP-tool drift warnings",
- "version": "0.3.0",
+ "description": "Scaffold, validate, and publish new Claude Code plugins with the canonical plugin contract — now including governed Claude Code mods (function hooks), ADR + smoke + Compatibility + namespace coordination + MCP-tool drift warnings. As a mod (ADR-445): /creator-mod (status, reserved names, a plugin contract check) and a status file the console shows",
+ "version": "0.4.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -18,6 +18,7 @@
"scaffolding",
"contract-bootstrap",
"mods",
- "function-hooks"
+ "function-hooks",
+ "mod"
]
}
diff --git a/plugins/ruflo-plugin-creator/README.md b/plugins/ruflo-plugin-creator/README.md
index f61bb0c7ec..4d41aba194 100644
--- a/plugins/ruflo-plugin-creator/README.md
+++ b/plugins/ruflo-plugin-creator/README.md
@@ -74,3 +74,12 @@ bash plugins/ruflo-plugin-creator/scripts/smoke.sh
- `ruflo-agentdb` — namespace convention owner; `agentdb_controllers` runtime is the canonical controller list
- `ruflo-cost-tracker`, `ruflo-market-data`, `ruflo-migrations`, `ruflo-observability` — each fixed namespace-routing bugs the scaffolder now warns about
- `ruflo-knowledge-graph`, `ruflo-market-data` — each fixed `embeddings_embed` references the scaffolder now warns about
+
+## As a mod
+
+Function-hook mod (ADR-445, pattern of `ruflo-agentdb`), loaded from `hooks/hooks.json` → `hooks/register.ts`. This plugin's own tools only search the plugin store, so there is no guard and no `userConfig`: the mod is a local command and a status file.
+
+- **Command**: `/creator-mod` answers locally with no model call, read-only. Verbs: `status`; `reserved <plugin-dir>` lists the command and skill names a plugin already uses (a mod command must not reuse one); `check <plugin-dir>` summarises its manifest, `hooks.json` modules and `userConfig` options. Paths with `..` are refused.
+- **Status file**: `.claude-flow/creator-mod/status.json` (`{version, updatedMs, checked, reserved, lastTarget}`).
+- **Safety**: no network, no process spawning.
+- **Test**: `claude plugin validate plugins/ruflo-plugin-creator`, `claude plugin test plugins/ruflo-plugin-creator`, `bash plugins/ruflo-plugin-creator/scripts/smoke.sh`. The runner sweeps in `templates/mod/tests` (the scaffold's own test, which only passes against the scaffold: `claude plugin test plugins/ruflo-plugin-creator/templates/mod`), so expect that one file to fail from the plugin root.
diff --git a/plugins/ruflo-plugin-creator/hooks/command.ts b/plugins/ruflo-plugin-creator/hooks/command.ts
new file mode 100644
index 0000000000..72897850bc
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/hooks/command.ts
@@ -0,0 +1,72 @@
+import type { Stats } from './status'
+
+/** `/creator-mod` is answered locally, read-only and takes no model turn. */
+export type CommandDeps = {
+ readonly stats: Stats
+ readonly read: (path: string) => Promise<string>
+ readonly list: (path: string) => Promise<readonly { readonly name: string; readonly kind: string }[]>
+}
+
+const HELP = ['/creator-mod status', '/creator-mod reserved <plugin-dir>', '/creator-mod check <plugin-dir>'].join('\n')
+
+/** A plugin directory the user typed: relative or absolute, never a parent traversal. */
+export const safeDir = (arg: string): string | undefined => {
+ const dir = arg.trim().replace(/\/+$/, '')
+ return dir === '' || dir.includes('\0') || dir.split('/').includes('..') ? undefined : dir
+}
+
+/** Names the plugin's markdown commands and skill directories already hold: a mod command may not reuse one. */
+async function reservedIn(dir: string, deps: CommandDeps): Promise<string[]> {
+ const names: string[] = []
+ for (const [sub, want] of [['commands', 'file'], ['skills', 'dir']] as const) {
+ try {
+ for (const e of await deps.list(`${dir}/${sub}`)) {
+ if (e.kind === want || e.kind === 'directory') names.push(e.name.replace(/\.md$/, ''))
+ }
+ } catch {
+ /* no such folder */
+ }
+ }
+ return [...new Set(names)].sort()
+}
+
+const readJson = async (deps: CommandDeps, path: string): Promise<Record<string, unknown> | undefined> => {
+ try {
+ const v: unknown = JSON.parse(await deps.read(path))
+ return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined
+ } catch {
+ return undefined
+ }
+}
+
+export async function answer(args: string, deps: CommandDeps): Promise<string> {
+ const [verb = '', ...rest] = args.trim().split(/\s+/)
+ const { stats } = deps
+
+ if (verb === '' || verb === 'help') return HELP
+ if (verb === 'status') return `checks run ${stats.checked} · reserved lookups ${stats.reserved}${stats.lastTarget ? ` · last ${stats.lastTarget}` : ''}`
+
+ if (verb !== 'reserved' && verb !== 'check') return `Unknown: ${verb}\n${HELP}`
+ const dir = safeDir(rest.join(' '))
+ if (dir === undefined) return `usage: /creator-mod ${verb} <plugin-dir> (no .. segments)`
+ stats.lastTarget = dir
+
+ if (verb === 'reserved') {
+ stats.reserved++
+ const names = await reservedIn(dir, deps)
+ return names.length ? `Names ${dir} already uses (a mod command must differ): ${names.join(', ')}` : `No commands or skills found under ${dir}.`
+ }
+
+ stats.checked++
+ const manifest = await readJson(deps, `${dir}/.claude-plugin/plugin.json`)
+ if (!manifest) return `${dir}: no readable .claude-plugin/plugin.json.`
+ const hooks = await readJson(deps, `${dir}/hooks/hooks.json`)
+ const modules = Array.isArray(hooks?.modules) ? (hooks.modules as unknown[]).length : 0
+ const config = typeof manifest.userConfig === 'object' && manifest.userConfig !== null ? Object.keys(manifest.userConfig).length : 0
+ const name = typeof manifest.name === 'string' ? manifest.name : '?'
+ return [
+ `${name} ${typeof manifest.version === 'string' ? manifest.version : '(no version)'}`,
+ `hooks.json ${hooks ? 'present' : 'absent'} · mod modules ${modules} · userConfig options ${config}`,
+ `reserved names: ${(await reservedIn(dir, deps)).join(', ') || 'none'}`,
+ ].join('\n')
+}
diff --git a/plugins/ruflo-plugin-creator/hooks/hooks.json b/plugins/ruflo-plugin-creator/hooks/hooks.json
new file mode 100644
index 0000000000..92326a668a
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/hooks/hooks.json
@@ -0,0 +1,4 @@
+{
+ "description": "Plugin creator as a mod (ADR-445): /creator-mod answers locally (status, reserved names, a plugin contract check) and a status file the console reads.",
+ "modules": ["./register.ts"]
+}
diff --git a/plugins/ruflo-plugin-creator/hooks/register.ts b/plugins/ruflo-plugin-creator/hooks/register.ts
new file mode 100644
index 0000000000..69ed442344
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/hooks/register.ts
@@ -0,0 +1,49 @@
+import type { Hook, Register } from 'claude-code'
+
+import { answer } from './command'
+import { newStats, STATUS_PATH, statusText, type Stats } from './status'
+
+type Dollar = Parameters<Hook<'session.start'>>[0]
+
+/** Everything one session of the mod keeps: its counters and the project root. */
+type Session = { readonly stats: Stats; root?: string }
+
+async function flush($: Dollar, s: Session): Promise<void> {
+ if (s.root === undefined) return
+ try {
+ await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.stats, await $.clock.now()))
+ } catch {
+ /* the status file is a courtesy */
+ }
+}
+
+/**
+ * The plugin creator as a mod (ADR-445): `/creator-mod` (status, reserved names, a contract check, all read-only and local) and a status file
+ * the console reads. No guard: this plugin's tools only search the plugin store. No network, no process.
+ */
+export const register: Register = on => {
+ const s: Session = { stats: newStats() }
+
+ on('session.start', async ($, e, next) => {
+ const result = await next(e)
+ try {
+ s.root = (await $.session.root()) as string | undefined
+ } catch {
+ /* no project root: the mod still answers, it just writes no status file */
+ }
+ try {
+ await $.command.register({ name: 'creator-mod', description: 'Plugin creator mod: status, reserved <dir>, check <dir>' })
+ } catch {
+ /* a name taken by another plugin must not stop the mod */
+ }
+ await flush($, s)
+ return result
+ })
+
+ /** `/creator-mod` (the plugin's `/create-plugin` is a prompt command, which no hook can answer). */
+ on('command.run', { command: 'creator-mod' }, async ($, e) => {
+ const text = await answer(typeof e.args === 'string' ? e.args : '', { stats: s.stats, read: p => $.fs.read(p), list: p => $.fs.list(p) })
+ await flush($, s)
+ return { text }
+ })
+}
diff --git a/plugins/ruflo-plugin-creator/hooks/status.ts b/plugins/ruflo-plugin-creator/hooks/status.ts
new file mode 100644
index 0000000000..39451b043c
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/hooks/status.ts
@@ -0,0 +1,9 @@
+/** Counters the mod keeps for the session and writes to `.claude-flow/creator-mod/status.json`. */
+export type Stats = { checked: number; reserved: number; lastTarget?: string }
+
+export const newStats = (): Stats => ({ checked: 0, reserved: 0 })
+
+export const STATUS_PATH = '.claude-flow/creator-mod/status.json'
+
+/** The file's text; `version` lets a reader refuse a shape it does not know. */
+export const statusText = (stats: Stats, nowMs: number): string => `${JSON.stringify({ version: 1, updatedMs: nowMs, ...stats }, null, 2)}\n`
diff --git a/plugins/ruflo-plugin-creator/scripts/smoke.sh b/plugins/ruflo-plugin-creator/scripts/smoke.sh
index 10d0cb7097..d46c6145de 100755
--- a/plugins/ruflo-plugin-creator/scripts/smoke.sh
+++ b/plugins/ruflo-plugin-creator/scripts/smoke.sh
@@ -7,9 +7,9 @@ step() { printf "→ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.3.0 with new keywords"
+step "1. plugin.json declares 0.4.0 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.3.0" ]]; then bad "expected 0.3.0, got '$v'"; else
+if [[ "$v" != "0.4.0" ]]; then bad "expected 0.4.0, got '$v'"; else
miss=""
for k in mcp scaffolding contract-bootstrap; do
grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
@@ -86,5 +86,23 @@ grep -q '"modules": \["./register.ts"\]' "$T/hooks/hooks.json" && grep -q '"User
&& grep -q "claude-code/testing" "$T/tests/register.test.ts" && [[ -f "$ROOT/skills/create-mod/SKILL.md" ]] \
&& ! grep -qE '\$\[' "$T/hooks/register.ts" && ok || bad "templates/mod incomplete"
+# M1. The mod (ADR-445): hooks module registered, files within the 500-line rule, no network or process access in the hooks
+step "M1. mod: hooks.json names register.ts, every hook file is present and under 500 lines"
+mod_ok=1
+grep -q '"./register.ts"' "$ROOT/hooks/hooks.json" || mod_ok=0
+for f in status command register; do
+ [[ -f "$ROOT/hooks/$f.ts" ]] || mod_ok=0
+ [[ $(wc -l < "$ROOT/hooks/$f.ts" 2>/dev/null || echo 9999) -le 500 ]] || mod_ok=0
+done
+[[ $mod_ok -eq 1 ]] && ok || bad "mod hooks incomplete or too long"
+
+step "M2. mod: no userConfig needed (read-only local command)"
+node -e '
+process.exit(require(process.argv[1]).userConfig === undefined ? 0 : 1)
+' "$ROOT/.claude-plugin/plugin.json" && ok || bad "unexpected userConfig"
+
+step "M3. mod: hooks never touch the network or spawn a process"
+if grep -nE '\$\.(http|process)\.|child_process|fetch\(' "$ROOT"/hooks/*.ts >/dev/null; then bad "network or process call in hooks"; else ok; fi
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-plugin-creator/tests/creator.test.ts b/plugins/ruflo-plugin-creator/tests/creator.test.ts
new file mode 100644
index 0000000000..5b747b4d63
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/tests/creator.test.ts
@@ -0,0 +1,85 @@
+import type { On } from 'claude-code'
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+tier('user')
+
+const ROOT = '/work'
+const START = { surface: 'terminal', isInteractive: true, cwd: ROOT } as const
+const STATUS = `${ROOT}/.claude-flow/creator-mod/status.json`
+const slash = (args: string) => ({ command: 'creator-mod', args, origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } }) as const
+
+/** The engine resolves paths against the real cwd; the fixture is keyed on the part the mod typed. */
+const rel = (p: string) => p.replace(/^.*\/plugins\/ruflo-plugin-creator\//, '')
+
+/** A project root, a file map for writes, and a small read-only plugin tree. */
+function world(on: On) {
+ const files = new Map<string, string>()
+ const tree: Record<string, string> = {
+ 'demo/.claude-plugin/plugin.json': JSON.stringify({ name: 'demo', version: '1.2.0', userConfig: { guard: {} } }),
+ 'demo/hooks/hooks.json': JSON.stringify({ modules: ['./register.ts'] }),
+ }
+ const dirs: Record<string, { name: string; kind: string; size: number; mtimeMs: number; isLink: boolean }[]> = {
+ 'demo/commands': [{ name: 'demo.md', kind: 'file', size: 1, mtimeMs: 0, isLink: false }],
+ 'demo/skills': [{ name: 'demo-skill', kind: 'directory', size: 0, mtimeMs: 0, isLink: false }],
+ }
+ on('session.start', ($, e) => ({ cwd: e.cwd }))
+ on('session.root', () => ({ value: ROOT }))
+ on('command.register', ($, e) => ({ value: { command: e.name } }))
+ on('fs.write', ($, e) => (files.set(e.path, e.text), { value: undefined }))
+ on('fs.read', ($, e) => {
+ const text = tree[rel(e.path)]
+ if (text === undefined) throw new Error('ENOENT')
+ return { value: text }
+ })
+ on('fs.list', ($, e) => {
+ const entries = dirs[rel(e.path ?? '')]
+ if (entries === undefined) throw new Error('ENOENT')
+ return { value: entries }
+ })
+ on('clock.now', () => ({ value: 5_000 }))
+ return { status: () => JSON.parse(files.get(STATUS) ?? '{}') }
+}
+
+describe('status file', () => {
+ test('written at session start, rewritten after a lookup', async ($, on) => {
+ const w = world(on)
+ await $.session.start(START)
+ expect(w.status()).toMatchObject({ version: 1, updatedMs: 5000, checked: 0, reserved: 0 })
+ await $.command.run(slash('check demo'))
+ expect(w.status()).toMatchObject({ checked: 1, lastTarget: 'demo' })
+ })
+})
+
+describe('/creator-mod', () => {
+ test('status and help answer locally', async ($, on) => {
+ world(on)
+ await $.session.start(START)
+ expect((await $.command.run(slash('status'))).text).toContain('checks run 0')
+ expect((await $.command.run(slash(''))).text).toContain('/creator-mod reserved <plugin-dir>')
+ expect((await $.command.run(slash('wat'))).text).toContain('Unknown: wat')
+ })
+
+ test('reserved lists the commands and skills a mod command must not reuse', async ($, on) => {
+ world(on)
+ await $.session.start(START)
+ const text = (await $.command.run(slash('reserved demo/'))).text ?? ''
+ expect(text).toContain('demo')
+ expect(text).toContain('demo-skill')
+ })
+
+ test('check reports the manifest, hooks and options', async ($, on) => {
+ world(on)
+ await $.session.start(START)
+ const text = (await $.command.run(slash('check demo'))).text ?? ''
+ expect(text).toContain('demo 1.2.0')
+ expect(text).toContain('mod modules 1 · userConfig options 1')
+ })
+
+ test('a missing plugin and a parent traversal are refused plainly', async ($, on) => {
+ world(on)
+ await $.session.start(START)
+ expect((await $.command.run(slash('check nowhere'))).text).toContain('no readable')
+ expect((await $.command.run(slash('check ../../etc'))).text).toContain('no .. segments')
+ expect((await $.command.run(slash('check'))).text).toContain('usage')
+ })
+})
diff --git a/plugins/ruflo-plugin-creator/tsconfig.json b/plugins/ruflo-plugin-creator/tsconfig.json
new file mode 100644
index 0000000000..e4ba54993e
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/tsconfig.json
@@ -0,0 +1,19 @@
+{
+ "//": "Self-contained on purpose: bundlers (vite/esbuild in the root CI vitest) load this file for every module they transform, so it must not extend a file that only exists after Claude Code (>= 2.1.287) has loaded the plugin. Claude Code writes its declarations to .claude-plugin/types/ (gitignored) on load or validate; tsc -p . then reads them through typeRoots.",
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "noEmit": true,
+ "skipLibCheck": true,
+ "jsx": "react",
+ "jsxFactory": "h",
+ "jsxFragmentFactory": "Fragment",
+ "typeRoots": ["./.claude-plugin/types"],
+ "types": ["claude-code", "claude-code-tools", "claude-code-mcp"]
+ },
+ "include": ["hooks", "tests"]
+}