@jsbot-tellus/core 2.5.1 → 2.7.0

package/src/core/plugin/loader.ts

@@ -4,7 +4,7 @@ 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 { readJsonFile } from './install-dir.js'
 import { NpmCliRunner, type NpmRunner } from './npm-runner.js'
 import type { AnyPluginDefinition } from './types.js'
 
@@ -13,7 +13,7 @@ type LoaderLogger = Pick<Logger, 'warn' | 'error'> & {
 }
 
 export interface LocalPluginLoaderOptions {
-    /** Build local plugins that have a build script but no dist. Defaults to true. */
+    /** Rebuild local plugins that have a build script on every load. Defaults to true. */
     autoBuild?: boolean | undefined
     /** Timeout for a single local plugin build. Defaults to 120 seconds. */
     buildTimeoutMs?: number | undefined
@@ -49,19 +49,7 @@ async function readBuildScript(directory: string): Promise<string | undefined> {
         : 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
-    }
-}
+type BuildOutcome = 'built' | 'missing-node-modules' | 'failed'
 
 async function buildLocalPlugin(
     directory: string,
@@ -69,22 +57,15 @@ async function buildLocalPlugin(
     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
-    }
-
+): Promise<BuildOutcome> {
     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}`
+            `cannot build local plugin ${name}: node_modules is missing; run npm install --prefix ${directory}`
         )
-        return false
+        return 'missing-node-modules'
     }
 
-    logger?.info?.(`building local plugin ${name}: dist directory not found`)
+    logger?.info?.(`building local plugin ${name}`)
 
     try {
         await runner.run(['run', 'build'], {
@@ -93,13 +74,12 @@ async function buildLocalPlugin(
         })
     } catch (error) {
         logger?.error(`failed to build local plugin ${name}`, error)
-        logger?.warn(`skipping local plugin ${name}: build failed`)
-        return false
+        return 'failed'
     }
 
     logger?.info?.(`built local plugin ${name}`)
 
-    return true
+    return 'built'
 }
 
 export async function loadPluginsFromDirectory(
@@ -127,7 +107,14 @@ export async function loadPluginsFromDirectory(
         let imported: unknown
 
         try {
-            imported = await import(pathToFileURL(file).href)
+            const info = await stat(file).catch(() => null)
+            const url = pathToFileURL(file)
+
+            if (info !== null) {
+                url.searchParams.set('v', String(info.mtimeMs))
+            }
+
+            imported = await import(url.href)
         } catch (error) {
             logger?.error(`failed to import plugin file: ${file}`, error)
             invalid.push(
@@ -170,22 +157,7 @@ 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 autoBuild = options.autoBuild !== false
     const runner = options.runner ?? new NpmCliRunner()
     const timeoutMs = options.buildTimeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS
 
@@ -195,24 +167,11 @@ export async function loadLocalPlugins(
 
         const directory = join(absolute, entry.name)
         const dist = join(directory, 'dist')
+        const hasBuildScript = (await readBuildScript(directory)) !== undefined
         let distInfo = await stat(dist).catch(() => null)
 
-        if (!distInfo?.isDirectory()) {
-            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(
+        if (autoBuild && hasBuildScript) {
+            const outcome = await buildLocalPlugin(
                 directory,
                 entry.name,
                 logger,
@@ -220,16 +179,32 @@ export async function loadLocalPlugins(
                 timeoutMs
             )
 
-            if (!built) continue
-
             distInfo = await stat(dist).catch(() => null)
 
             if (!distInfo?.isDirectory()) {
+                const reason =
+                    outcome === 'built'
+                        ? 'build finished but dist directory not found'
+                        : outcome === 'missing-node-modules'
+                          ? 'node_modules is missing and dist directory not found'
+                          : 'build failed and dist directory not found'
+
+                logger?.warn(`skipping local plugin ${entry.name}: ${reason}`)
+                continue
+            }
+
+            if (outcome !== 'built') {
                 logger?.warn(
-                    `skipping local plugin ${entry.name}: build finished but dist directory not found`
+                    `using existing dist for local plugin ${entry.name}: rebuild failed`
                 )
-                continue
             }
+        } else if (!distInfo?.isDirectory()) {
+            logger?.warn(
+                hasBuildScript
+                    ? `skipping local plugin ${entry.name}: dist directory not found and automatic build is disabled`
+                    : `skipping local plugin ${entry.name}: dist directory not found and package.json has no build script`
+            )
+            continue
         }
 
         plugins.push(...(await loadPluginsFromDirectory(dist, logger)))

package/src/core/plugin/params/declaration.ts

@@ -1,11 +1,18 @@
 import {
     declarationError,
     type CommandParamType,
+    type ParamLength,
     type ParamSpec,
 } from './types.js'
-import { parseBoolean, parseTimeValue, unquote } from './values.js'
+import {
+    measureLength,
+    parseBoolean,
+    parseTimeValue,
+    unquote,
+} from './values.js'
 
 const NAME_PATTERN = /^[\p{L}_][\p{L}\p{N}_-]*$/u
+const LENGTH_PATTERN = /^(\d*)\.\.(\d*)$/
 
 export function parseType(value: string): CommandParamType {
     switch (value) {
@@ -23,6 +30,90 @@ export function parseType(value: string): CommandParamType {
     }
 }
 
+interface ParsedType {
+    type: CommandParamType
+    length?: ParamLength | undefined
+}
+
+function parseLengthNumber(raw: string, token: string): number {
+    const value = Number(raw)
+
+    if (!Number.isSafeInteger(value)) {
+        throw declarationError(`长度限制不是安全的整数：${token}`)
+    }
+
+    return value
+}
+
+function parseLength(raw: string, token: string): ParamLength {
+    const value = raw.trim()
+    const match = LENGTH_PATTERN.exec(value)
+
+    if (!match) {
+        throw declarationError(`非法的长度限制 "${raw}"：${token}`)
+    }
+
+    const minRaw = match[1] ?? ''
+    const maxRaw = match[2] ?? ''
+
+    if (minRaw === '' && maxRaw === '') {
+        throw declarationError(`长度限制不能为空：${token}`)
+    }
+
+    const min = minRaw === '' ? undefined : parseLengthNumber(minRaw, token)
+    const max = maxRaw === '' ? undefined : parseLengthNumber(maxRaw, token)
+
+    if (min !== undefined && max !== undefined && min > max) {
+        throw declarationError(`长度下限不能大于上限：${token}`)
+    }
+
+    return { min, max }
+}
+
+function parseTypeDeclaration(raw: string, token: string): ParsedType {
+    const value = raw.trim()
+    const open = value.indexOf('(')
+
+    if (open < 0) {
+        return { type: parseType(value) }
+    }
+
+    if (!value.endsWith(')')) {
+        throw declarationError(`非法的参数声明 "${token}"`)
+    }
+
+    const type = parseType(value.slice(0, open).trim())
+    const length = parseLength(value.slice(open + 1, -1), token)
+
+    if (type !== 'string' && type !== 'text') {
+        throw declarationError(`只有 string/text 参数支持长度限制：${token}`)
+    }
+
+    return { type, length }
+}
+
+function validateDefaultLength(
+    name: string,
+    value: string,
+    length: ParamLength | undefined
+): void {
+    if (length === undefined) return
+
+    const measured = measureLength(value)
+
+    if (length.min !== undefined && measured < length.min) {
+        throw declarationError(
+            `参数 ${name} 的默认值至少需要 ${length.min} 个字符`
+        )
+    }
+
+    if (length.max !== undefined && measured > length.max) {
+        throw declarationError(
+            `参数 ${name} 的默认值不能超过 ${length.max} 个字符`
+        )
+    }
+}
+
 export function validateName(value: string): string {
     const name = value.trim()
 
@@ -120,7 +211,13 @@ export function parseToken(token: string): ParamSpec {
             throw declarationError('变长参数必须使用 [ ]')
         }
 
-        const name = validateName(inner.slice(3))
+        const rest = inner.slice(3)
+
+        if (rest.includes('(')) {
+            throw declarationError(`变长参数不支持长度限制：${token}`)
+        }
+
+        const name = validateName(rest)
 
         return {
             name,
@@ -140,20 +237,30 @@ export function parseToken(token: string): ParamSpec {
     const defaultRaw = equals >= 0 ? inner.slice(equals + 1).trim() : undefined
     const colon = head.indexOf(':')
     const name = validateName(colon >= 0 ? head.slice(0, colon) : head)
-    const type = parseType(colon >= 0 ? head.slice(colon + 1).trim() : 'string')
+    const { type, length } = parseTypeDeclaration(
+        colon >= 0 ? head.slice(colon + 1) : 'string',
+        token
+    )
 
     if (required && defaultRaw !== undefined) {
         throw declarationError(`必填参数不能有默认值：${token}`)
     }
 
     if (defaultRaw !== undefined) {
+        const defaultValue = parseDefaultValue(type, defaultRaw, name)
+
+        if (typeof defaultValue === 'string') {
+            validateDefaultLength(name, defaultValue, length)
+        }
+
         return {
             name,
             type,
             required,
             rest: false,
             hasDefault: true,
-            defaultValue: parseDefaultValue(type, defaultRaw, name),
+            defaultValue,
+            length,
         }
     }
 
@@ -163,6 +270,7 @@ export function parseToken(token: string): ParamSpec {
         required,
         rest: false,
         hasDefault: false,
+        length,
     }
 }
 

package/src/core/plugin/params/input.ts

@@ -4,7 +4,7 @@ import {
     type ParamSpec,
     type ParsedCommandParams,
 } from './types.js'
-import { parseAt, parseBoolean, parseTime } from './values.js'
+import { measureLength, parseAt, parseBoolean, parseTime } from './values.js'
 
 export function tokenizeInput(input: string, usage: string): InputToken[] {
     const tokens: InputToken[] = []
@@ -101,6 +101,32 @@ export function tokenizeInput(input: string, usage: string): InputToken[] {
     return tokens
 }
 
+function enforceLength(spec: ParamSpec, value: string, usage: string): string {
+    const length = spec.length
+
+    if (length === undefined) {
+        return value
+    }
+
+    const measured = measureLength(value)
+
+    if (length.min !== undefined && measured < length.min) {
+        throw new CommandParamsError(
+            `参数 ${spec.name} 至少需要 ${length.min} 个字符`,
+            usage
+        )
+    }
+
+    if (length.max !== undefined && measured > length.max) {
+        throw new CommandParamsError(
+            `参数 ${spec.name} 不能超过 ${length.max} 个字符`,
+            usage
+        )
+    }
+
+    return value
+}
+
 export function parseValue(
     spec: ParamSpec,
     raw: string,
@@ -108,6 +134,7 @@ export function parseValue(
 ): unknown {
     switch (spec.type) {
         case 'string':
+            return enforceLength(spec, raw, usage)
         case 'text':
             return raw
         case 'number': {
@@ -218,7 +245,7 @@ export function parseInput(
             const value =
                 remaining === 1 ? token.value : input.slice(token.start).trim()
 
-            args.push(value)
+            args.push(enforceLength(spec, value, usage))
             index = tokens.length
             continue
         }

package/src/core/plugin/params/type-level.ts

@@ -8,12 +8,16 @@ type TrimRight<Source extends string> =
 
 type Trim<Source extends string> = TrimLeft<TrimRight<Source>>
 
+type StripLength<Type extends string> =
+    Trim<Type> extends `${infer Base}(${string})` ? Trim<Base> : Trim<Type>
+
 type ParamValue<Type extends string> =
-    Trim<Type> extends 'string' | 'text'
+    StripLength<Type> extends 'string' | 'text'
         ? string
-        : Trim<Type> extends 'number' | 'integer' | 'at' | 'reply' | 'time'
+        : StripLength<Type> extends
+                'number' | 'integer' | 'at' | 'reply' | 'time'
           ? number
-          : Trim<Type> extends 'boolean'
+          : StripLength<Type> extends 'boolean'
             ? boolean
             : unknown
 

package/src/core/plugin/params/types.ts

@@ -30,6 +30,11 @@ export class CommandParamsError extends Error {
     }
 }
 
+export interface ParamLength {
+    min?: number | undefined
+    max?: number | undefined
+}
+
 export interface ParamSpec {
     name: string
     type: CommandParamType
@@ -37,6 +42,7 @@ export interface ParamSpec {
     rest: boolean
     hasDefault: boolean
     defaultValue?: unknown
+    length?: ParamLength | undefined
 }
 
 export interface InputToken {

package/src/core/plugin/params/values.ts

@@ -37,6 +37,10 @@ export function unquote(value: string): string {
     return result
 }
 
+export function measureLength(value: string): number {
+    return Array.from(value).length
+}
+
 export function parseBoolean(value: string): boolean | null {
     const normalized = value.trim().toLowerCase()
 

package/src/core/plugin/types.ts

@@ -1,6 +1,8 @@
 import type {
+    OneBotGroupMessageEvent,
     OneBotMessageEvent,
     OneBotNoticeEvent,
+    OneBotPrivateMessageEvent,
     OneBotRequestEvent,
     OutgoingMessage,
     SnowLumaEvent,
@@ -17,6 +19,10 @@ import type { CommandParamArgs } from './command-params.js'
 
 export type EventType = 'message' | 'notice' | 'request' | 'meta'
 
+export type MessageType = 'group' | 'private'
+
+export type MessageTypeFilter = MessageType | readonly MessageType[]
+
 export interface CommandMatch {
     command: string
     prefix: string
@@ -28,6 +34,7 @@ export interface CommandInfo {
     name: string
     aliases: string[]
     permission: Permission
+    messageTypes: MessageType[]
     description?: string | undefined
     usage?: string | undefined
     pluginId: string
@@ -59,6 +66,16 @@ export type MessageHandler = (
     context: EventContext<OneBotMessageEvent>
 ) => void | Promise<void>
 
+export type GroupMessageHandler = (
+    event: OneBotGroupMessageEvent,
+    context: EventContext<OneBotGroupMessageEvent>
+) => void | Promise<void>
+
+export type PrivateMessageHandler = (
+    event: OneBotPrivateMessageEvent,
+    context: EventContext<OneBotPrivateMessageEvent>
+) => void | Promise<void>
+
 export type NoticeHandler = (
     event: OneBotNoticeEvent,
     context: EventContext<OneBotNoticeEvent>
@@ -80,6 +97,7 @@ export interface CommandOptions<Declaration extends string = string> {
     aliases?: string[] | undefined
     prefixes?: string[] | undefined
     permission?: Permission | undefined
+    messageType?: MessageTypeFilter | undefined
     description?: string | undefined
     params?: Declaration | undefined
 }
@@ -127,6 +145,8 @@ export interface CommandRegistrar extends CommandGroupRegistrar {
 
 export interface EventRegistrar {
     onMessage(handler: MessageHandler): () => void
+    onGroupMessage(handler: GroupMessageHandler): () => void
+    onPrivateMessage(handler: PrivateMessageHandler): () => void
     onNotice(options: NoticeOptions, handler: NoticeHandler): () => void
     onRequest(options: RequestOptions, handler: RequestHandler): () => void
 }