@jsbot-tellus/core 2.0.3 → 2.2.0

package/src/core/dispatch/command.ts

@@ -1,10 +1,21 @@
+import type { OneBotMessageEvent } from '@snowluma/sdk'
+import {
+    compileCommandParams,
+    type CommandParamArgs,
+    type CompiledCommandParams,
+} from '../plugin/command-params.js'
 import type {
+    CommandGroupOptions,
+    CommandGroupRegistrar,
     CommandHandler,
     CommandInfo,
     CommandMatch,
+    CommandOptions,
 } from '../plugin/types.js'
 import type { Permission } from '../security/permission.js'
 
+type AnyCommandHandler = CommandHandler<OneBotMessageEvent, any[]>
+
 export interface CommandRegistration {
     pluginId: string
     name: string
@@ -12,7 +23,21 @@ export interface CommandRegistration {
     prefixes: string[]
     permission: Permission
     description?: string | undefined
-    handler: CommandHandler
+    params?: string | undefined
+    paramsParser?: CompiledCommandParams | undefined
+    usage?: string | undefined
+    handler: AnyCommandHandler
+}
+
+export interface CommandGroupRegistration {
+    pluginId: string
+    name: string
+    aliases: string[]
+    prefixes: string[]
+    permission: Permission
+    description?: string | undefined
+    params?: string | undefined
+    handler?: AnyCommandHandler | undefined
 }
 
 export interface RegisteredCommand {
@@ -20,80 +45,167 @@ export interface RegisteredCommand {
     match: CommandMatch
 }
 
-export class CommandRegistry {
-    private readonly index = new Map<string, Map<string, CommandRegistration>>()
-    private readonly registrations = new Set<CommandRegistration>()
-    private readonly byPlugin = new Map<string, Set<CommandRegistration>>()
+interface GroupChild {
+    name: string
+    description?: string | undefined
+    usage?: string | undefined
+}
 
-    register(registration: CommandRegistration): () => void {
-        const names = [
-            ...new Set(
-                [registration.name, ...registration.aliases].map((name) =>
-                    name.toLowerCase()
-                )
-            ),
-        ]
-        const prefixes = [...new Set(registration.prefixes)]
+interface GroupScope {
+    registrar: CommandGroupRegistrar
+    disposeAll: () => void
+    track: (dispose: () => void, cleanup?: () => void) => () => void
+}
 
-        for (const prefix of prefixes) {
-            for (const name of names) {
-                const existing = this.index.get(prefix)?.get(name)
+function normalizeSegment(label: string, value: string): string {
+    const trimmed = value.trim()
 
-                if (existing) {
-                    throw new Error(`command conflict: ${prefix}${name}`)
-                }
-            }
-        }
+    if (!trimmed) {
+        throw new Error(`${label} must not be empty`)
+    }
 
-        for (const prefix of prefixes) {
-            const bucket =
-                this.index.get(prefix) ?? new Map<string, CommandRegistration>()
+    if (/\s/.test(trimmed)) {
+        throw new Error(
+            `${label} must be a single segment; use commands.group() for multi-level commands`
+        )
+    }
 
-            for (const name of names) {
-                bucket.set(name, registration)
-            }
+    return trimmed
+}
 
-            this.index.set(prefix, bucket)
-        }
+function uniqueStrings(values: string[]): string[] {
+    const seen = new Set<string>()
+    const result: string[] = []
 
-        this.registrations.add(registration)
+    for (const value of values) {
+        const key = value.toLowerCase()
 
-        const pluginSet =
-            this.byPlugin.get(registration.pluginId) ??
-            new Set<CommandRegistration>()
-        pluginSet.add(registration)
-        this.byPlugin.set(registration.pluginId, pluginSet)
+        if (seen.has(key)) continue
 
-        let disposed = false
+        seen.add(key)
+        result.push(value)
+    }
 
-        return () => {
-            if (disposed) return
+    return result
+}
 
-            disposed = true
+function groupBases(name: string, aliases: string[]): string[] {
+    return uniqueStrings([
+        normalizeSegment('group name', name),
+        ...aliases.map((alias) => normalizeSegment('group alias', alias)),
+    ])
+}
 
-            for (const prefix of prefixes) {
-                const bucket = this.index.get(prefix)
+function composedBases(
+    parentBases: string[],
+    name: string,
+    aliases: string[],
+    kind: 'command' | 'group'
+): string[] {
+    const variants = uniqueStrings([
+        normalizeSegment(`${kind} name`, name),
+        ...aliases.map((alias) => normalizeSegment(`${kind} alias`, alias)),
+    ])
+    const bases: string[] = []
+    const seen = new Set<string>()
+
+    for (const parent of parentBases) {
+        for (const variant of variants) {
+            const path = `${parent} ${variant}`
+            const key = path.toLowerCase()
+
+            if (seen.has(key)) continue
+
+            seen.add(key)
+            bases.push(path)
+        }
+    }
 
-                if (!bucket) continue
+    return bases
+}
 
-                for (const name of names) {
-                    if (bucket.get(name) === registration) {
-                        bucket.delete(name)
-                    }
-                }
+function createGroupUsageHandler(children: GroupChild[]): AnyCommandHandler {
+    return async (_event, context, match) => {
+        const root = `${match.prefix}${match.command}`
+        const names = children.map((child) => child.name)
+        const lines = [
+            names.length > 0
+                ? `用法：${root} <${names.join('|')}>`
+                : `用法：${root}`,
+        ]
 
-                if (bucket.size === 0) {
-                    this.index.delete(prefix)
-                }
-            }
+        for (const child of children) {
+            const usage = child.usage !== undefined ? ` ${child.usage}` : ''
+            const command = `${root} ${child.name}${usage}`
 
-            this.registrations.delete(registration)
-            pluginSet.delete(registration)
+            lines.push(
+                child.description !== undefined
+                    ? `${command} - ${child.description}`
+                    : command
+            )
+        }
 
-            if (pluginSet.size === 0) {
-                this.byPlugin.delete(registration.pluginId)
-            }
+        await context.send(lines.join('\n'))
+    }
+}
+
+export class CommandRegistry {
+    private readonly index = new Map<string, Map<string, CommandRegistration>>()
+    private readonly registrations = new Set<CommandRegistration>()
+    private readonly byPlugin = new Map<string, Set<CommandRegistration>>()
+
+    register(registration: CommandRegistration): () => void {
+        const name = normalizeSegment('command name', registration.name)
+        const aliases = uniqueStrings(
+            registration.aliases.map((alias) =>
+                normalizeSegment('command alias', alias)
+            )
+        ).filter((alias) => alias.toLowerCase() !== name.toLowerCase())
+        const normalized = this.withParams({
+            ...registration,
+            name,
+            aliases,
+        })
+
+        return this.insert(normalized, [name, ...aliases])
+    }
+
+    group(
+        registration: CommandGroupRegistration,
+        setup: (group: CommandGroupRegistrar) => void
+    ): () => void {
+        const prefixes = uniqueStrings(registration.prefixes)
+        const bases = groupBases(registration.name, registration.aliases)
+        const children: GroupChild[] = []
+        const scope = this.createGroupScope(
+            registration.pluginId,
+            bases,
+            prefixes,
+            registration.permission,
+            children
+        )
+
+        try {
+            setup(scope.registrar)
+
+            const dispose = this.registerGroupRoot(
+                registration.pluginId,
+                bases,
+                prefixes,
+                registration.permission,
+                registration.description,
+                registration.params,
+                registration.handler,
+                children
+            )
+
+            scope.track(dispose)
+        } catch (error) {
+            scope.disposeAll()
+            throw error
         }
+
+        return scope.disposeAll
     }
 
     removePlugin(pluginId: string): void {
@@ -102,12 +214,11 @@ export class CommandRegistry {
         if (!registrations) return
 
         for (const registration of [...registrations]) {
-            const prefixes = registration.prefixes
             const names = [registration.name, ...registration.aliases].map(
                 (name) => name.toLowerCase()
             )
 
-            for (const prefix of prefixes) {
+            for (const prefix of registration.prefixes) {
                 const bucket = this.index.get(prefix)
 
                 if (!bucket) continue
@@ -139,6 +250,9 @@ export class CommandRegistry {
                 ...(registration.description !== undefined
                     ? { description: registration.description }
                     : {}),
+                ...(registration.usage !== undefined
+                    ? { usage: registration.usage }
+                    : {}),
                 pluginId: registration.pluginId,
             }))
     }
@@ -159,22 +273,316 @@ export class CommandRegistry {
 
             if (!text) continue
 
-            const [head = '', ...args] = text.split(/\s+/)
-            const registration = this.index.get(prefix)?.get(head.toLowerCase())
+            const tokens = [...text.matchAll(/\S+/g)]
+
+            if (tokens.length === 0) continue
+
+            for (let count = tokens.length; count >= 1; count -= 1) {
+                const matched = tokens.slice(0, count)
+                const first = matched[0]
+                const last = matched[matched.length - 1]
+
+                if (!first || !last) continue
+
+                const key = matched
+                    .map((token) => token[0])
+                    .join(' ')
+                    .toLowerCase()
+                const registration = this.index.get(prefix)?.get(key)
 
-            if (!registration) continue
+                if (!registration) continue
 
-            return {
-                registration,
-                match: {
-                    command: head,
-                    prefix,
-                    args,
-                    rest: text.slice(head.length).trim(),
-                },
+                const start = first.index ?? 0
+                const end = (last.index ?? 0) + last[0].length
+
+                return {
+                    registration,
+                    match: {
+                        command: text
+                            .slice(start, end)
+                            .replace(/\s+/g, ' ')
+                            .trim(),
+                        prefix,
+                        args: tokens.slice(count).map((token) => token[0]),
+                        rest: text.slice(end).trim(),
+                    },
+                }
             }
         }
 
         return null
     }
+
+    private withParams(registration: CommandRegistration): CommandRegistration {
+        if (registration.params === undefined) return registration
+
+        const compiled = compileCommandParams(registration.params)
+
+        return {
+            ...registration,
+            paramsParser: compiled,
+            usage: compiled.usage,
+        }
+    }
+
+    private insert(
+        registration: CommandRegistration,
+        paths: string[]
+    ): () => void {
+        const prefixes = uniqueStrings(registration.prefixes)
+        const names = uniqueStrings(paths)
+
+        for (const prefix of prefixes) {
+            for (const name of names) {
+                const existing = this.index.get(prefix)?.get(name.toLowerCase())
+
+                if (existing) {
+                    throw new Error(`command conflict: ${prefix}${name}`)
+                }
+            }
+        }
+
+        for (const prefix of prefixes) {
+            const bucket =
+                this.index.get(prefix) ?? new Map<string, CommandRegistration>()
+
+            for (const name of names) {
+                bucket.set(name.toLowerCase(), registration)
+            }
+
+            this.index.set(prefix, bucket)
+        }
+
+        this.registrations.add(registration)
+
+        const pluginSet =
+            this.byPlugin.get(registration.pluginId) ??
+            new Set<CommandRegistration>()
+        pluginSet.add(registration)
+        this.byPlugin.set(registration.pluginId, pluginSet)
+
+        let disposed = false
+
+        return () => {
+            if (disposed) return
+
+            disposed = true
+
+            for (const prefix of prefixes) {
+                const bucket = this.index.get(prefix)
+
+                if (!bucket) continue
+
+                for (const name of names) {
+                    if (bucket.get(name.toLowerCase()) === registration) {
+                        bucket.delete(name.toLowerCase())
+                    }
+                }
+
+                if (bucket.size === 0) {
+                    this.index.delete(prefix)
+                }
+            }
+
+            this.registrations.delete(registration)
+            pluginSet.delete(registration)
+
+            if (pluginSet.size === 0) {
+                this.byPlugin.delete(registration.pluginId)
+            }
+        }
+    }
+
+    private createGroupScope(
+        pluginId: string,
+        bases: string[],
+        prefixes: string[],
+        permission: Permission,
+        children: GroupChild[]
+    ): GroupScope {
+        const disposers: Array<() => void> = []
+        let disposed = false
+
+        const track = (
+            dispose: () => void,
+            cleanup?: () => void
+        ): (() => void) => {
+            let done = false
+
+            const tracked = (): void => {
+                if (done) return
+
+                done = true
+                cleanup?.()
+                dispose()
+            }
+
+            disposers.push(tracked)
+
+            return tracked
+        }
+
+        const disposeAll = (): void => {
+            if (disposed) return
+
+            disposed = true
+
+            for (const dispose of disposers.splice(0).reverse()) {
+                dispose()
+            }
+        }
+
+        const registrar: CommandGroupRegistrar = {
+            register: <Declaration extends string = string>(
+                options: CommandOptions<Declaration>,
+                handler: CommandHandler<
+                    OneBotMessageEvent,
+                    CommandParamArgs<Declaration>
+                >
+            ) => {
+                const childBases = composedBases(
+                    bases,
+                    options.name,
+                    options.aliases ?? [],
+                    'command'
+                )
+                const name = childBases[0]
+
+                if (!name) {
+                    throw new Error('command name must not be empty')
+                }
+
+                const registration = this.withParams({
+                    pluginId,
+                    name,
+                    aliases: childBases.slice(1),
+                    prefixes: options.prefixes ?? prefixes,
+                    permission: options.permission ?? permission,
+                    ...(options.description !== undefined
+                        ? { description: options.description }
+                        : {}),
+                    ...(options.params !== undefined
+                        ? { params: options.params }
+                        : {}),
+                    handler,
+                })
+                const dispose = this.insert(registration, childBases)
+                const record: GroupChild = {
+                    name: options.name.trim(),
+                    ...(options.description !== undefined
+                        ? { description: options.description }
+                        : {}),
+                    ...(registration.usage !== undefined
+                        ? { usage: registration.usage }
+                        : {}),
+                }
+
+                children.push(record)
+
+                return track(dispose, () => {
+                    const index = children.indexOf(record)
+
+                    if (index >= 0) {
+                        children.splice(index, 1)
+                    }
+                })
+            },
+
+            group: <Declaration extends string = string>(
+                options: CommandGroupOptions<Declaration>,
+                nestedSetup: (group: CommandGroupRegistrar) => void
+            ) => {
+                const nestedBases = composedBases(
+                    bases,
+                    options.name,
+                    options.aliases ?? [],
+                    'group'
+                )
+                const nestedPrefixes = options.prefixes ?? prefixes
+                const nestedPermission = options.permission ?? permission
+                const nestedChildren: GroupChild[] = []
+                const nestedScope = this.createGroupScope(
+                    pluginId,
+                    nestedBases,
+                    nestedPrefixes,
+                    nestedPermission,
+                    nestedChildren
+                )
+
+                try {
+                    nestedSetup(nestedScope.registrar)
+
+                    const dispose = this.registerGroupRoot(
+                        pluginId,
+                        nestedBases,
+                        nestedPrefixes,
+                        nestedPermission,
+                        options.description,
+                        options.params,
+                        options.handler,
+                        nestedChildren
+                    )
+
+                    nestedScope.track(dispose)
+                } catch (error) {
+                    nestedScope.disposeAll()
+                    throw error
+                }
+
+                const record: GroupChild = {
+                    name: options.name.trim(),
+                    ...(options.description !== undefined
+                        ? { description: options.description }
+                        : {}),
+                    ...(options.params !== undefined
+                        ? {
+                              usage: compileCommandParams(options.params).usage,
+                          }
+                        : {}),
+                }
+
+                children.push(record)
+
+                return track(nestedScope.disposeAll, () => {
+                    const index = children.indexOf(record)
+
+                    if (index >= 0) {
+                        children.splice(index, 1)
+                    }
+                })
+            },
+        }
+
+        return { registrar, disposeAll, track }
+    }
+
+    private registerGroupRoot(
+        pluginId: string,
+        bases: string[],
+        prefixes: string[],
+        permission: Permission,
+        description: string | undefined,
+        params: string | undefined,
+        handler: AnyCommandHandler | undefined,
+        children: GroupChild[]
+    ): () => void {
+        const name = bases[0]
+
+        if (!name) {
+            throw new Error('group name must not be empty')
+        }
+
+        const registration = this.withParams({
+            pluginId,
+            name,
+            aliases: bases.slice(1),
+            prefixes,
+            permission,
+            ...(description !== undefined ? { description } : {}),
+            ...(params !== undefined ? { params } : {}),
+            handler: handler ?? createGroupUsageHandler(children),
+        })
+
+        return this.insert(registration, bases)
+    }
 }