ruflo-plugin-creator

1import type { Hook, Register } from 'claude-code'
2
3import { answer } from './command'
4import { newStats, STATUS_PATH, statusText, type Stats } from './status'
5
6type Dollar = Parameters<Hook<'session.start'>>[0]
7
8/** Everything one session of the mod keeps: its counters and the project root. */
9type Session = { readonly stats: Stats; root?: string }
10
11async function flush($: Dollar, s: Session): Promise<void> {
12  if (s.root === undefined) return
13  try {
14    await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.stats, await $.clock.now()))
15  } catch {
16    /* the status file is a courtesy */
17  }
18}
19
20/**
21 * 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
22 * the console reads. No guard: this plugin's tools only search the plugin store. No network, no process.
23 */
24export const register: Register = on => {
25  const s: Session = { stats: newStats() }
26
27  on('session.start', async ($, e, next) => {
28    const result = await next(e)
29    try {
30      s.root = (await $.session.root()) as string | undefined
31    } catch {
32      /* no project root: the mod still answers, it just writes no status file */
33    }
34    try {
35      await $.command.register({ name: 'creator-mod', description: 'Plugin creator mod: status, reserved <dir>, check <dir>' })
36    } catch {
37      /* a name taken by another plugin must not stop the mod */
38    }
39    await flush($, s)
40    return result
41  })
42
43  /** `/creator-mod` (the plugin's `/create-plugin` is a prompt command, which no hook can answer). */
44  on('command.run', { command: 'creator-mod' }, async ($, e) => {
45    const text = await answer(typeof e.args === 'string' ? e.args : '', { stats: s.stats, read: p => $.fs.read(p), list: p => $.fs.list(p) })
46    await flush($, s)
47    return { text }
48  })
49}
50

1import type { Stats } from './status'
2
3/** `/creator-mod` is answered locally, read-only and takes no model turn. */
4export type CommandDeps = {
5  readonly stats: Stats
6  readonly read: (path: string) => Promise<string>
7  readonly list: (path: string) => Promise<readonly { readonly name: string; readonly kind: string }[]>
8}
9
10const HELP = ['/creator-mod status', '/creator-mod reserved <plugin-dir>', '/creator-mod check <plugin-dir>'].join('\n')
11
12/** A plugin directory the user typed: relative or absolute, never a parent traversal. */
13export const safeDir = (arg: string): string | undefined => {
14  const dir = arg.trim().replace(/\/+$/, '')
15  return dir === '' || dir.includes('\0') || dir.split('/').includes('..') ? undefined : dir
16}
17
18/** Names the plugin's markdown commands and skill directories already hold: a mod command may not reuse one. */
19async function reservedIn(dir: string, deps: CommandDeps): Promise<string[]> {
20  const names: string[] = []
21  for (const [sub, want] of [['commands', 'file'], ['skills', 'dir']] as const) {
22    try {
23      for (const e of await deps.list(`${dir}/${sub}`)) {
24        if (e.kind === want || e.kind === 'directory') names.push(e.name.replace(/\.md$/, ''))
25      }
26    } catch {
27      /* no such folder */
28    }
29  }
30  return [...new Set(names)].sort()
31}
32
33const readJson = async (deps: CommandDeps, path: string): Promise<Record<string, unknown> | undefined> => {
34  try {
35    const v: unknown = JSON.parse(await deps.read(path))
36    return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined
37  } catch {
38    return undefined
39  }
40}
41
42export async function answer(args: string, deps: CommandDeps): Promise<string> {
43  const [verb = '', ...rest] = args.trim().split(/\s+/)
44  const { stats } = deps
45
46  if (verb === '' || verb === 'help') return HELP
47  if (verb === 'status') return `checks run ${stats.checked} · reserved lookups ${stats.reserved}${stats.lastTarget ? ` · last ${stats.lastTarget}` : ''}`
48
49  if (verb !== 'reserved' && verb !== 'check') return `Unknown: ${verb}\n${HELP}`
50  const dir = safeDir(rest.join(' '))
51  if (dir === undefined) return `usage: /creator-mod ${verb} <plugin-dir>  (no .. segments)`
52  stats.lastTarget = dir
53
54  if (verb === 'reserved') {
55    stats.reserved++
56    const names = await reservedIn(dir, deps)
57    return names.length ? `Names ${dir} already uses (a mod command must differ): ${names.join(', ')}` : `No commands or skills found under ${dir}.`
58  }
59
60  stats.checked++
61  const manifest = await readJson(deps, `${dir}/.claude-plugin/plugin.json`)
62  if (!manifest) return `${dir}: no readable .claude-plugin/plugin.json.`
63  const hooks = await readJson(deps, `${dir}/hooks/hooks.json`)
64  const modules = Array.isArray(hooks?.modules) ? (hooks.modules as unknown[]).length : 0
65  const config = typeof manifest.userConfig === 'object' && manifest.userConfig !== null ? Object.keys(manifest.userConfig).length : 0
66  const name = typeof manifest.name === 'string' ? manifest.name : '?'
67  return [
68    `${name} ${typeof manifest.version === 'string' ? manifest.version : '(no version)'}`,
69    `hooks.json ${hooks ? 'present' : 'absent'} · mod modules ${modules} · userConfig options ${config}`,
70    `reserved names: ${(await reservedIn(dir, deps)).join(', ') || 'none'}`,
71  ].join('\n')
72}
73

1/** Counters the mod keeps for the session and writes to `.claude-flow/creator-mod/status.json`. */
2export type Stats = { checked: number; reserved: number; lastTarget?: string }
3
4export const newStats = (): Stats => ({ checked: 0, reserved: 0 })
5
6export const STATUS_PATH = '.claude-flow/creator-mod/status.json'
7
8/** The file's text; `version` lets a reader refuse a shape it does not know. */
9export const statusText = (stats: Stats, nowMs: number): string => `${JSON.stringify({ version: 1, updatedMs: nowMs, ...stats }, null, 2)}\n`
10