@jsbot-tellus/core 2.0.3 → 2.2.0

package/src/core/plugin/loader.ts

@@ -1,12 +1,106 @@
-import { stat } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { readdir, stat } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
 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,
@@ -60,3 +154,86 @@ export async function loadPluginsFromDirectory(
 
     return plugins
 }
+
+export async function loadLocalPlugins(
+    root: string,
+    logger?: LoaderLogger | undefined,
+    options: LocalPluginLoaderOptions = {}
+): Promise<AnyPluginDefinition[]> {
+    const absolute = resolve(root)
+    const info = await stat(absolute).catch(() => null)
+
+    if (!info?.isDirectory()) return []
+
+    const entries = (await readdir(absolute, { withFileTypes: true })).sort(
+        (a, b) => a.name.localeCompare(b.name)
+    )
+    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 directory = join(absolute, entry.name)
+        const dist = join(directory, 'dist')
+        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(
+                directory,
+                entry.name,
+                logger,
+                runner,
+                timeoutMs
+            )
+
+            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)))
+    }
+
+    return plugins
+}

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'
 
@@ -28,6 +29,7 @@ export interface CommandInfo {
     aliases: string[]
     permission: Permission
     description?: string | undefined
+    usage?: string | undefined
     pluginId: string
 }
 
@@ -44,10 +46,12 @@ export interface EventContext<TEvent extends SnowLumaEvent = SnowLumaEvent> {
 
 export type CommandHandler<
     TEvent extends OneBotMessageEvent = OneBotMessageEvent,
+    TArgs extends unknown[] = [],
 > = (
     event: TEvent,
     context: EventContext<TEvent>,
-    match: CommandMatch
+    match: CommandMatch,
+    ...args: TArgs
 ) => void | Promise<void>
 
 export type MessageHandler = (
@@ -71,12 +75,35 @@ 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?: Declaration | undefined
+}
+
+export interface CommandGroupOptions<
+    Declaration extends string = string,
+> extends CommandOptions<Declaration> {
+    handler?:
+        | CommandHandler<OneBotMessageEvent, CommandParamArgs<Declaration>>
+        | undefined
+}
+
+export interface CommandGroupRegistrar {
+    register<Declaration extends string = string>(
+        options: CommandOptions<Declaration>,
+        handler: CommandHandler<
+            OneBotMessageEvent,
+            CommandParamArgs<Declaration>
+        >
+    ): () => void
+    group<Declaration extends string = string>(
+        options: CommandGroupOptions<Declaration>,
+        setup: (group: CommandGroupRegistrar) => void
+    ): () => void
 }
 
 export interface NoticeOptions {
@@ -94,8 +121,7 @@ export interface MiddlewareOptions {
     priority?: number | undefined
 }
 
-export interface CommandRegistrar {
-    register(options: CommandOptions, handler: CommandHandler): () => void
+export interface CommandRegistrar extends CommandGroupRegistrar {
     list(): ReadonlyArray<CommandInfo>
 }
 
@@ -164,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