@jsbot-tellus/core 2.1.0 → 2.3.0

package/src/core/plugin/command-params.ts

@@ -1,5 +1,7 @@
+import { parseSegments } from '@snowluma/sdk'
+
 export type CommandParamType =
-    'string' | 'text' | 'number' | 'integer' | 'boolean'
+    'string' | 'text' | 'number' | 'integer' | 'boolean' | 'at'
 
 export interface ParsedCommandParams {
     args: unknown[]
@@ -48,6 +50,7 @@ function parseType(value: string): CommandParamType {
         case 'number':
         case 'integer':
         case 'boolean':
+        case 'at':
             return value
         default:
             throw declarationError(`未知的参数类型 "${value}"`)
@@ -177,6 +180,35 @@ function parseBoolean(value: string): boolean | null {
     return null
 }
 
+function parseAt(value: string, name: string, usage: string): number {
+    const raw = value.trim()
+    const segments = parseSegments(raw)
+    const segment = segments[0]
+
+    if (segments.length === 1 && segment?.type === 'at') {
+        const qq = segment.data.qq
+
+        if (qq !== 'all') {
+            const parsed = Number(qq)
+
+            if (Number.isSafeInteger(parsed) && parsed > 0) {
+                return parsed
+            }
+        }
+    } else if (/^\d+$/.test(raw)) {
+        const parsed = Number(raw)
+
+        if (Number.isSafeInteger(parsed) && parsed > 0) {
+            return parsed
+        }
+    }
+
+    throw new CommandParamsError(
+        `参数 ${name} 需要 @ 一个用户或填写 QQ 号`,
+        usage
+    )
+}
+
 function parseDefaultValue(
     type: CommandParamType,
     raw: string,
@@ -215,6 +247,8 @@ function parseDefaultValue(
 
             return boolean
         }
+        case 'at':
+            throw declarationError(`参数 ${name} 不支持默认值`)
     }
 }
 
@@ -405,6 +439,16 @@ function tokenizeInput(input: string, usage: string): InputToken[] {
 
             if (/\s/.test(current)) break
 
+            if (current === '[' && input.startsWith('[CQ:', index)) {
+                const close = input.indexOf(']', index + 4)
+
+                if (close >= 0) {
+                    value += input.slice(index, close + 1)
+                    index = close + 1
+                    continue
+                }
+            }
+
             if (current === '"' || current === "'") {
                 quote = current
                 index += 1
@@ -480,6 +524,8 @@ function parseValue(spec: ParamSpec, raw: string, usage: string): unknown {
 
             return value
         }
+        case 'at':
+            return parseAt(raw, spec.name, usage)
     }
 }
 
@@ -593,3 +639,75 @@ export function compileCommandParams(
         },
     }
 }
+
+type Whitespace = ' ' | '\n' | '\r' | '\t' | '\v' | '\f'
+
+type TrimLeft<Source extends string> =
+    Source extends `${Whitespace}${infer Rest}` ? TrimLeft<Rest> : Source
+
+type TrimRight<Source extends string> =
+    Source extends `${infer Rest}${Whitespace}` ? TrimRight<Rest> : Source
+
+type Trim<Source extends string> = TrimLeft<TrimRight<Source>>
+
+type ParamValue<Type extends string> =
+    Trim<Type> extends 'string' | 'text'
+        ? string
+        : Trim<Type> extends 'number' | 'integer' | 'at'
+          ? number
+          : Trim<Type> extends 'boolean'
+            ? boolean
+            : unknown
+
+interface VariadicParam {
+    readonly variadic: true
+}
+
+type ParamType<Head extends string> = Head extends `${string}:${infer Type}`
+    ? ParamValue<Type>
+    : string
+
+type ParamElement<Body extends string, Required extends boolean> =
+    Trim<Body> extends `...${string}`
+        ? VariadicParam
+        : Trim<Body> extends `${infer Head}=${string}`
+          ? ParamType<Head>
+          : Required extends true
+            ? ParamType<Body>
+            : ParamType<Body> | undefined
+
+type AppendParam<Acc extends unknown[], Element> = [Element] extends [
+    VariadicParam,
+]
+    ? [...Acc, ...string[]]
+    : [...Acc, Element]
+
+type ParseCommandParams<Source extends string, Acc extends unknown[] = []> =
+    Trim<Source> extends ''
+        ? Acc
+        : Trim<Source> extends `<${infer Body}>${infer Rest}`
+          ? ParamElement<Body, true> extends VariadicParam
+              ? any[]
+              : ParseCommandParams<
+                    Rest,
+                    AppendParam<Acc, ParamElement<Body, true>>
+                >
+          : Trim<Source> extends `[${infer Body}]${infer Rest}`
+            ? ParamElement<Body, false> extends VariadicParam
+                ? Trim<Rest> extends ''
+                    ? [...Acc, ...string[]]
+                    : any[]
+                : ParseCommandParams<
+                      Rest,
+                      AppendParam<Acc, ParamElement<Body, false>>
+                  >
+            : any[]
+
+/**
+ * 把 `params` 声明字符串推导成 handler 的位置参数 tuple。
+ *
+ * 非字面量声明（例如运行时拼接的 `string`）或无法解析的声明会回退为
+ * `any[]`，以保证现有插件仍然可以编译。
+ */
+export type CommandParamArgs<Declaration extends string> =
+    string extends Declaration ? any[] : ParseCommandParams<Declaration>

package/src/core/plugin/context.ts

@@ -4,6 +4,7 @@ import type { Router } from '../dispatch/router.js'
 import type { TaskQueue } from '../dispatch/task-queue.js'
 import type { Logger } from '../logging/logger.js'
 import type { SessionStore } from '../storage/session.js'
+import type { CommandParamArgs } from './command-params.js'
 import type { PluginKV } from './kv.js'
 import type {
     CommandGroupOptions,
@@ -43,9 +44,12 @@ export function createPluginContext<TConfig>(
         core: deps.core,
 
         commands: {
-            register<TArgs extends unknown[] = []>(
-                options: CommandOptions,
-                handler: CommandHandler<OneBotMessageEvent, TArgs>
+            register<Declaration extends string = string>(
+                options: CommandOptions<Declaration>,
+                handler: CommandHandler<
+                    OneBotMessageEvent,
+                    CommandParamArgs<Declaration>
+                >
             ) {
                 return deps.router.registerCommand({
                     pluginId: id,
@@ -68,8 +72,8 @@ export function createPluginContext<TConfig>(
                     handler,
                 })
             },
-            group<TArgs extends unknown[] = []>(
-                options: CommandGroupOptions<TArgs>,
+            group<Declaration extends string = string>(
+                options: CommandGroupOptions<Declaration>,
                 setup: (group: CommandGroupRegistrar) => void
             ) {
                 return deps.router.registerCommandGroup(

package/src/core/plugin/loader.ts

@@ -4,9 +4,103 @@ import { pathToFileURL } from 'node:url'
 import fg from 'fast-glob'
 import type { Logger } from '../logging/logger.js'
 import { collectPluginExports } from './exports.js'
+import { readInstallState, readJsonFile } from './install-dir.js'
+import { NpmCliRunner, type NpmRunner } from './npm-runner.js'
 import type { AnyPluginDefinition } from './types.js'
 
-type LoaderLogger = Pick<Logger, 'warn' | 'error'>
+type LoaderLogger = Pick<Logger, 'warn' | 'error'> & {
+    info?: Logger['info'] | undefined
+}
+
+export interface LocalPluginLoaderOptions {
+    /** Build local plugins that have a build script but no dist. Defaults to true. */
+    autoBuild?: boolean | undefined
+    /** Timeout for a single local plugin build. Defaults to 120 seconds. */
+    buildTimeoutMs?: number | undefined
+    /** npm runner override, mainly for tests. */
+    runner?: NpmRunner | undefined
+}
+
+const DEFAULT_BUILD_TIMEOUT_MS = 120_000
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+async function directoryExists(path: string): Promise<boolean> {
+    const info = await stat(path).catch(() => null)
+
+    return info?.isDirectory() ?? false
+}
+
+async function readBuildScript(directory: string): Promise<string | undefined> {
+    const manifest = await readJsonFile(join(directory, 'package.json')).catch(
+        () => undefined
+    )
+
+    if (!isRecord(manifest) || !isRecord(manifest['scripts'])) {
+        return undefined
+    }
+
+    const build = manifest['scripts']['build']
+
+    return typeof build === 'string' && build.trim().length > 0
+        ? build
+        : undefined
+}
+
+async function readManagedDirectories(
+    root: string
+): Promise<Set<string> | null> {
+    try {
+        const state = await readInstallState(root)
+
+        return new Set(
+            Object.values(state.packages).map((record) => record.dir)
+        )
+    } catch {
+        return null
+    }
+}
+
+async function buildLocalPlugin(
+    directory: string,
+    name: string,
+    logger: LoaderLogger | undefined,
+    runner: NpmRunner,
+    timeoutMs: number
+): Promise<boolean> {
+    if ((await readBuildScript(directory)) === undefined) {
+        logger?.warn(
+            `skipping local plugin ${name}: dist directory not found and package.json has no build script`
+        )
+        return false
+    }
+
+    if (!(await directoryExists(join(directory, 'node_modules')))) {
+        logger?.warn(
+            `skipping local plugin ${name}: dist directory not found and node_modules is missing; run npm install --prefix ${directory}`
+        )
+        return false
+    }
+
+    logger?.info?.(`building local plugin ${name}: dist directory not found`)
+
+    try {
+        await runner.run(['run', 'build'], {
+            cwd: directory,
+            timeoutMs,
+        })
+    } catch (error) {
+        logger?.error(`failed to build local plugin ${name}`, error)
+        logger?.warn(`skipping local plugin ${name}: build failed`)
+        return false
+    }
+
+    logger?.info?.(`built local plugin ${name}`)
+
+    return true
+}
 
 export async function loadPluginsFromDirectory(
     directory: string,
@@ -63,7 +157,8 @@ export async function loadPluginsFromDirectory(
 
 export async function loadLocalPlugins(
     root: string,
-    logger?: LoaderLogger | undefined
+    logger?: LoaderLogger | undefined,
+    options: LocalPluginLoaderOptions = {}
 ): Promise<AnyPluginDefinition[]> {
     const absolute = resolve(root)
     const info = await stat(absolute).catch(() => null)
@@ -75,18 +170,66 @@ export async function loadLocalPlugins(
     )
     const plugins: AnyPluginDefinition[] = []
 
+    let autoBuild = options.autoBuild !== false
+    let managed = new Set<string>()
+
+    if (autoBuild) {
+        const directories = await readManagedDirectories(absolute)
+
+        if (directories === null) {
+            logger?.warn(
+                'cannot read plugin install state; automatic local plugin build is disabled'
+            )
+            autoBuild = false
+        } else {
+            managed = directories
+        }
+    }
+
+    const runner = options.runner ?? new NpmCliRunner()
+    const timeoutMs = options.buildTimeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS
+
     for (const entry of entries) {
         if (!entry.isDirectory() || entry.name.startsWith('.')) continue
         if (entry.name === 'node_modules') continue
 
-        const dist = join(absolute, entry.name, 'dist')
-        const distInfo = await stat(dist).catch(() => null)
+        const directory = join(absolute, entry.name)
+        const dist = join(directory, 'dist')
+        let distInfo = await stat(dist).catch(() => null)
 
         if (!distInfo?.isDirectory()) {
-            logger?.warn(
-                `skipping local plugin ${entry.name}: dist directory not found`
+            if (!autoBuild) {
+                logger?.warn(
+                    `skipping local plugin ${entry.name}: dist directory not found`
+                )
+                continue
+            }
+
+            if (managed.has(entry.name)) {
+                logger?.warn(
+                    `skipping local plugin ${entry.name}: dist directory not found (installed package is expected to include dist)`
+                )
+                continue
+            }
+
+            const built = await buildLocalPlugin(
+                directory,
+                entry.name,
+                logger,
+                runner,
+                timeoutMs
             )
-            continue
+
+            if (!built) continue
+
+            distInfo = await stat(dist).catch(() => null)
+
+            if (!distInfo?.isDirectory()) {
+                logger?.warn(
+                    `skipping local plugin ${entry.name}: build finished but dist directory not found`
+                )
+                continue
+            }
         }
 
         plugins.push(...(await loadPluginsFromDirectory(dist, logger)))

package/src/core/plugin/types.ts

@@ -13,6 +13,7 @@ import type { SendOptions } from '../messaging/sender.js'
 import type { PluginKV } from '../plugin/kv.js'
 import type { Permission } from '../security/permission.js'
 import type { SessionStore } from '../storage/session.js'
+import type { CommandParamArgs } from './command-params.js'
 
 export type EventType = 'message' | 'notice' | 'request' | 'meta'
 
@@ -74,28 +75,33 @@ export type PluginMiddleware = (
     next: () => Promise<void>
 ) => void | Promise<void>
 
-export interface CommandOptions {
+export interface CommandOptions<Declaration extends string = string> {
     name: string
     aliases?: string[] | undefined
     prefixes?: string[] | undefined
     permission?: Permission | undefined
     description?: string | undefined
-    params?: string | undefined
+    params?: Declaration | undefined
 }
 
 export interface CommandGroupOptions<
-    TArgs extends unknown[] = [],
-> extends CommandOptions {
-    handler?: CommandHandler<OneBotMessageEvent, TArgs> | undefined
+    Declaration extends string = string,
+> extends CommandOptions<Declaration> {
+    handler?:
+        | CommandHandler<OneBotMessageEvent, CommandParamArgs<Declaration>>
+        | undefined
 }
 
 export interface CommandGroupRegistrar {
-    register<TArgs extends unknown[] = []>(
-        options: CommandOptions,
-        handler: CommandHandler<OneBotMessageEvent, TArgs>
+    register<Declaration extends string = string>(
+        options: CommandOptions<Declaration>,
+        handler: CommandHandler<
+            OneBotMessageEvent,
+            CommandParamArgs<Declaration>
+        >
     ): () => void
-    group<TArgs extends unknown[] = []>(
-        options: CommandGroupOptions<TArgs>,
+    group<Declaration extends string = string>(
+        options: CommandGroupOptions<Declaration>,
         setup: (group: CommandGroupRegistrar) => void
     ): () => void
 }
@@ -184,7 +190,7 @@ export interface CoreServices {
         can(actual: Permission, required: Permission): boolean
     }
     commands: {
-        list(): ReadonlyArray<CommandInfo>
+        list(event?: SnowLumaEvent): ReadonlyArray<CommandInfo>
     }
     plugins: PluginStatus
     installer: PluginInstaller

package/src/plugins/core/index.ts

@@ -38,7 +38,7 @@ export const corePlugin = definePlugin({
             async (event, context) => {
                 const role = ctx.core.roles.roleOf(event.user_id)
                 const commands = ctx.core.commands
-                    .list()
+                    .list(event)
                     .filter((command) =>
                         ctx.core.roles.can(role, command.permission)
                     )