@jsbot-tellus/core 2.3.0 → 2.5.0

package/src/app.ts

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
-import { resolve } from 'node:path'
+import type { SnowLumaEvent } from '@snowluma/sdk'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { parseArgs } from 'node:util'
+import { fileURLToPath } from 'node:url'
 import { createBotClient } from './core/client.js'
 import type { AppConfig } from './core/config/schema.js'
 import {
@@ -10,15 +13,25 @@ import {
     resolveDataDir,
 } from './core/config/loader.js'
 import { Kernel } from './core/kernel.js'
+import { ConfigStore } from './core/web/config-store.js'
+import { EventFeed } from './core/web/event-feed.js'
+import { LogBuffer } from './core/logging/log-buffer.js'
 import {
     createLogger,
+    defaultLogSink,
     parseLogLevel,
+    type LogSink,
     type Logger,
 } from './core/logging/logger.js'
 import { NpmPluginInstaller } from './core/plugin/installer.js'
 import { loadLocalPlugins } from './core/plugin/loader.js'
-import type { AnyPluginDefinition } from './core/plugin/types.js'
-import { openDatabase } from './core/storage/database.js'
+import type {
+    AnyPluginDefinition,
+    PluginInstaller,
+} from './core/plugin/types.js'
+import { openDatabase, type Database } from './core/storage/database.js'
+import { WebUiServer } from './core/web/server.js'
+import type { WebUiAddress, WebUiDeps } from './core/web/types.js'
 import { builtinPlugins } from './plugins/index.js'
 
 const LOCAL_PLUGIN_DIR = 'plugins'
@@ -89,6 +102,13 @@ interface RuntimeSpec {
 interface Runtime {
     spec: RuntimeSpec
     kernel: Kernel
+    database: Database
+    installer: PluginInstaller
+}
+
+interface StaticBinding {
+    host: string
+    port: number
 }
 
 async function loadRuntimeSpec(
@@ -130,7 +150,8 @@ async function loadRuntimeSpec(
 function createRuntime(
     spec: RuntimeSpec,
     settings: RuntimeSettings,
-    onRestart: () => void
+    onRestart: () => void,
+    onEvent: (event: SnowLumaEvent) => void
 ): Runtime {
     const { logger } = settings
     const installer = new NpmPluginInstaller({
@@ -158,9 +179,51 @@ function createRuntime(
         plugins: spec.plugins,
         installer,
         onRestart,
+        onEvent,
     })
 
-    return { spec, kernel }
+    return { spec, kernel, database, installer }
+}
+
+function describeError(error: unknown): string {
+    if (error instanceof Error) {
+        return error.stack ?? `${error.name}: ${error.message}`
+    }
+
+    return String(error)
+}
+
+function credentialSignature(config: AppConfig): string {
+    const webui = config.webui
+
+    return [webui.username ?? '', webui.password ?? ''].join(':')
+}
+
+function resolveStaticDir(): string | null {
+    const scriptDir = dirname(fileURLToPath(import.meta.url))
+    const candidates = [
+        join(scriptDir, 'webui'),
+        resolve(process.cwd(), 'dist/webui'),
+    ]
+
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, 'index.html'))) return candidate
+    }
+
+    return null
+}
+
+function readVersion(): string {
+    try {
+        const pkgPath = new URL('../package.json', import.meta.url)
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
+            version?: string
+        }
+
+        return pkg.version ?? 'unknown'
+    } catch {
+        return 'unknown'
+    }
 }
 
 async function main(): Promise<void> {
@@ -179,11 +242,22 @@ async function main(): Promise<void> {
         return
     }
 
+    const logs = new LogBuffer()
+    const events = new EventFeed()
+    const tapEvents = (event: SnowLumaEvent): void => {
+        events.add(event)
+    }
+    const sink: LogSink = (record) => {
+        defaultLogSink(record)
+        logs.push(record)
+    }
+
     const logger = createLogger({
         level: parseLogLevel(
             pick(values['log-level']) ?? process.env.BOT_LOG_LEVEL
         ),
         scope: 'app',
+        sink,
     })
 
     const configPath = resolveConfigPath({
@@ -202,48 +276,22 @@ async function main(): Promise<void> {
         dataDir,
     }
 
+    // Config file errors remain fatal: there is nothing the WebUI can restore
+    // from when the config cannot even be parsed.
+    const initialSpec = await loadRuntimeSpec(settings)
+
     let runtime: Runtime | null = null
+    let currentConfig: AppConfig = initialSpec.config
+    let generation = 0
+    let startupError: string | null = null
     let shuttingDown = false
     let restarting = false
     let restartPending = false
     let restartTimer: NodeJS.Timeout | null = null
-
-    const shutdown = async (signal: string, exitCode = 0): Promise<void> => {
-        if (shuttingDown) return
-
-        shuttingDown = true
-
-        if (restartTimer !== null) {
-            clearTimeout(restartTimer)
-            restartTimer = null
-        }
-
-        logger.info(`received ${signal}, shutting down`)
-
-        try {
-            await runtime?.kernel.stop()
-            process.exit(exitCode)
-        } catch (error) {
-            logger.error('shutdown failed', error)
-            process.exit(1)
-        }
-    }
-
-    const requestRestart = (): void => {
-        if (shuttingDown) return
-
-        if (restarting) {
-            restartPending = true
-            return
-        }
-
-        if (restartTimer !== null) return
-
-        restartTimer = setTimeout(() => {
-            restartTimer = null
-            void restartRuntime()
-        }, 250)
-    }
+    let restartTail: Promise<boolean> = Promise.resolve(true)
+    let exclusiveTail: Promise<unknown> = Promise.resolve()
+    let boundWebUi: StaticBinding | null = null
+    let credentials = credentialSignature(initialSpec.config)
 
     const restartDrainTimeout = (previous: Runtime | null): number => {
         const installTimeout =
@@ -252,115 +300,198 @@ async function main(): Promise<void> {
         return Math.max(installTimeout, 5_000) * 2 + 5_000
     }
 
-    const restartRuntime = async (): Promise<void> => {
-        if (shuttingDown || restarting) return
+    const restartRuntimeOnce = async (): Promise<boolean> => {
+        if (shuttingDown) return false
 
         restarting = true
         restartPending = false
 
         const previous = runtime
-        let stopped = false
-        let restarted = false
 
         logger.info('restarting runtime')
 
         try {
-            // Stop accepting new events so no command can start another install
-            // while the replacement runtime is being prepared.
             previous?.kernel.pause()
 
             const drainTimeout = restartDrainTimeout(previous)
-            const drained =
-                previous === null
-                    ? true
-                    : await previous.kernel.drain(drainTimeout)
 
-            // Restart requests raised by drained tasks are covered by the spec
-            // loaded below; requests that arrive later are preserved.
-            restartPending = false
+            if (previous !== null) {
+                const drained = await previous.kernel.drain(drainTimeout)
 
-            if (shuttingDown) return
+                if (!drained) {
+                    logger.warn('runtime restart drain timed out, cancelling')
+                }
 
-            let spec: RuntimeSpec
+                restartPending = false
 
-            if (drained) {
-                spec = await loadRuntimeSpec(settings)
+                if (shuttingDown) return false
 
-                if (shuttingDown) return
+                await previous.kernel.stop()
+            }
 
-                await previous?.kernel.stop()
-                stopped = true
-            } else {
-                logger.warn(
-                    'runtime restart drain timed out, cancelling pending tasks'
-                )
+            if (shuttingDown) return false
 
-                await previous?.kernel.stop()
-                stopped = true
-
-                // Kernel.stop() aborts pending tasks. Wait for their rollback
-                // to finish before the replacement runtime touches the same
-                // install directory.
-                const settled =
-                    previous === null
-                        ? true
-                        : await previous.kernel.drain(drainTimeout)
-
-                if (!settled) {
-                    logger.warn(
-                        'cancelled tasks are still running after restart drain'
-                    )
-                }
+            const spec = await loadRuntimeSpec(settings)
 
-                if (shuttingDown) return
+            currentConfig = spec.config
 
-                spec = await loadRuntimeSpec(settings)
-            }
+            const next = createRuntime(
+                spec,
+                settings,
+                requestRestart,
+                tapEvents
+            )
 
-            if (shuttingDown) return
+            runtime = next
+            await next.kernel.start()
 
-            runtime = createRuntime(spec, settings, requestRestart)
-            await runtime.kernel.start()
-            restarted = true
-            logger.info('runtime restarted')
-        } catch (error) {
-            logger.error('runtime restart failed', error)
+            generation += 1
+            startupError = null
 
-            if (!stopped) {
-                previous?.kernel.resume()
-                return
-            }
+            const signature = credentialSignature(currentConfig)
 
-            if (previous !== null) {
-                try {
-                    await runtime?.kernel.stop()
-                    runtime = createRuntime(
-                        previous.spec,
-                        settings,
-                        requestRestart
-                    )
-                    await runtime.kernel.start()
-                    logger.warn('restored previous runtime')
-                    return
-                } catch (fallbackError) {
-                    logger.error(
-                        'failed to restore previous runtime',
-                        fallbackError
-                    )
-                }
+            if (signature !== credentials) {
+                credentials = signature
+                server.invalidateSessions()
             }
 
-            await shutdown('restart failure', 1)
+            logger.info('runtime restarted')
+
+            return true
+        } catch (error) {
+            runtime = null
+            startupError = describeError(error)
+            logger.error('runtime restart failed', error)
+
+            return false
         } finally {
             restarting = false
 
-            if (restarted && restartPending && !shuttingDown) {
+            if (restartPending && !shuttingDown) {
                 restartPending = false
                 requestRestart()
             }
         }
     }
 
+    const restartRuntime = (): Promise<boolean> => {
+        const run = restartTail.then(restartRuntimeOnce, restartRuntimeOnce)
+
+        restartTail = run.then(
+            () => true,
+            () => false
+        )
+
+        return run
+    }
+
+    const requestRestart = (): void => {
+        if (shuttingDown) return
+
+        if (restarting) {
+            restartPending = true
+            return
+        }
+
+        if (restartTimer !== null) return
+
+        restartTimer = setTimeout(() => {
+            restartTimer = null
+            void restartRuntime()
+        }, 250)
+    }
+
+    const store = new ConfigStore({
+        configPath,
+        getPlugins: () => runtime?.spec.plugins ?? [],
+        restart: () => restartRuntime(),
+    })
+
+    const deps: WebUiDeps = {
+        logger: logger.child('webui'),
+        paths: {
+            configPath,
+            dataDir,
+            pluginDir: initialSpec.pluginDir,
+            staticDir: resolveStaticDir(),
+        },
+        version: readVersion(),
+        logs,
+        events,
+        getWebUiConfig: () => currentConfig.webui,
+        readConfig: () => store.read(),
+        validateConfig: (value) => store.validate(value),
+        applyConfig: (value, baseHash) => store.apply(value, baseHash),
+        restart: () => restartRuntime(),
+        requestRestart,
+        pause: () => runtime?.kernel.pause(),
+        resume: () => runtime?.kernel.resume(),
+        getListening: () => server.address,
+        invalidateSessions: () => server.invalidateSessions(),
+        runExclusive: async <T>(task: () => Promise<T>): Promise<T> => {
+            const run = exclusiveTail.then(task, task)
+
+            exclusiveTail = run.then(
+                () => undefined,
+                () => undefined
+            )
+
+            return run
+        },
+        getRuntime: () =>
+            runtime === null
+                ? null
+                : {
+                      generation,
+                      config: runtime.spec.config,
+                      kernel: runtime.kernel,
+                      api: runtime.kernel.api,
+                      database: runtime.database,
+                      installer: runtime.installer,
+                      plugins: runtime.spec.plugins,
+                  },
+        isRestarting: () => restarting,
+        getStartupError: () => startupError,
+        getRequiresProcessRestart: () => {
+            const webui = currentConfig.webui
+
+            if (boundWebUi === null) return webui.enabled
+
+            if (!webui.enabled) return true
+
+            return (
+                webui.host !== boundWebUi.host || webui.port !== boundWebUi.port
+            )
+        },
+    }
+
+    const server = new WebUiServer({
+        config: initialSpec.config.webui,
+        deps,
+    })
+
+    const shutdown = async (signal: string, exitCode = 0): Promise<void> => {
+        if (shuttingDown) return
+
+        shuttingDown = true
+
+        if (restartTimer !== null) {
+            clearTimeout(restartTimer)
+            restartTimer = null
+        }
+
+        logger.info(`received ${signal}, shutting down`)
+
+        try {
+            await runtime?.kernel.stop()
+            await server.stop()
+            process.exit(exitCode)
+        } catch (error) {
+            logger.error('shutdown failed', error)
+            process.exit(1)
+        }
+    }
+
     process.once('SIGINT', () => {
         void shutdown('SIGINT')
     })
@@ -369,9 +500,46 @@ async function main(): Promise<void> {
         void shutdown('SIGTERM')
     })
 
-    const spec = await loadRuntimeSpec(settings)
-    runtime = createRuntime(spec, settings, requestRestart)
-    await runtime.kernel.start()
+    // Start the WebUI before the kernel so it stays online when startup fails.
+    if (initialSpec.config.webui.enabled) {
+        const address: WebUiAddress | null = await server.start(
+            initialSpec.config.webui
+        )
+
+        if (address !== null) {
+            boundWebUi = {
+                host: address.host,
+                port: address.port,
+            }
+        }
+    }
+
+    try {
+        runtime = createRuntime(
+            initialSpec,
+            settings,
+            requestRestart,
+            tapEvents
+        )
+        await runtime.kernel.start()
+
+        generation = 1
+        startupError = null
+        credentials = credentialSignature(currentConfig)
+        logger.info('runtime started')
+    } catch (error) {
+        runtime = null
+        startupError = describeError(error)
+        logger.error('runtime startup failed', error)
+
+        if (boundWebUi === null) {
+            await shutdown('startup failure', 1)
+        } else {
+            logger.info(
+                'webui stays online; fix the configuration on the config page and restart the runtime'
+            )
+        }
+    }
 }
 
 await main().catch((error: unknown) => {

package/src/core/client.ts

@@ -19,6 +19,7 @@ export interface BotClientOptions {
 }
 
 export interface BotClient {
+    readonly isConnected: boolean
     use(middleware: EventMiddleware): () => void
     connect(): Promise<void>
     close(): void
@@ -74,6 +75,9 @@ export function createBotClient(options: BotClientOptions): BotClient {
     })
 
     return {
+        get isConnected() {
+            return client.isConnected
+        },
         use: (middleware) => client.use(middleware),
         connect: () => client.connect(),
         close: () => client.close(),

package/src/core/config/schema.ts

@@ -55,12 +55,51 @@ export const installerConfigSchema = z
     })
     .strict()
 
+export const webuiConfigSchema = z
+    .object({
+        enabled: z.boolean().default(false),
+        host: z.string().trim().min(1).max(255).default('127.0.0.1'),
+        port: z.number().int().min(1).max(65535).default(8787),
+        username: z.string().trim().min(1).max(64).optional(),
+        password: z.string().min(8).max(256).optional(),
+        sessionTtlHours: z.number().int().min(1).max(720).default(12),
+        trustProxy: z.boolean().default(false),
+    })
+    .strict()
+    .superRefine((value, context) => {
+        if (!value.enabled) return
+
+        if (value.username === undefined) {
+            context.addIssue({
+                code: 'custom',
+                message: 'username is required when webui is enabled',
+                path: ['username'],
+            })
+        }
+
+        if (value.password === undefined) {
+            context.addIssue({
+                code: 'custom',
+                message: 'password is required when webui is enabled',
+                path: ['password'],
+            })
+        }
+    })
+    .default({
+        enabled: false,
+        host: '127.0.0.1',
+        port: 8787,
+        sessionTtlHours: 12,
+        trustProxy: false,
+    })
+
 export const appConfigSchema = z
     .object({
         url: z.url({ protocol: /^wss?$/ }).default('ws://127.0.0.1:3001/'),
         accessToken: z.string().min(1).optional(),
         roles: rolesConfigSchema,
         message: messageConfigSchema,
+        webui: webuiConfigSchema,
         plugins: z.record(z.string(), pluginEnvelopeSchema).default({}),
         installer: installerConfigSchema.default({
             enabled: false,
@@ -77,6 +116,7 @@ export type PluginEnvelope = z.infer<typeof pluginEnvelopeSchema>
 export type MessageConfig = z.infer<typeof messageConfigSchema>
 export type RolesConfig = z.infer<typeof rolesConfigSchema>
 export type InstallerConfig = z.infer<typeof installerConfigSchema>
+export type WebUiConfig = z.infer<typeof webuiConfigSchema>
 export type AppConfig = z.infer<typeof appConfigSchema>
 
 export function formatConfigIssues(error: z.ZodError, prefix?: string): string {

package/src/core/dispatch/command.ts

@@ -89,6 +89,12 @@ function uniqueStrings(values: string[]): string[] {
     return result
 }
 
+const LEADING_REPLY = /^(?:\[CQ:reply(?:,[^\]]*)?\]\s*)+/
+
+function stripLeadingReply(raw: string): string {
+    return raw.replace(LEADING_REPLY, '')
+}
+
 function groupBases(name: string, aliases: string[]): string[] {
     return uniqueStrings([
         normalizeSegment('group name', name),
@@ -258,7 +264,7 @@ export class CommandRegistry {
     }
 
     match(rawMessage: string): RegisteredCommand | null {
-        const raw = rawMessage.trim()
+        const raw = stripLeadingReply(rawMessage.trim()).trim()
 
         if (!raw) return null
 

package/src/core/dispatch/router.ts

@@ -53,6 +53,7 @@ export interface RouterDeps {
     roles: RoleService
     gate: PluginGate
     logger: Logger
+    onEvent?: ((event: SnowLumaEvent) => void) | undefined
 }
 
 type AnyCommandHandler = CommandHandler<OneBotMessageEvent, any[]>
@@ -106,12 +107,14 @@ export class Router {
     private readonly handlers = new HandlerRegistry()
     private readonly middlewares = new MiddlewareRegistry()
     private readonly active = new Set<Promise<void>>()
+    private readonly onEvent: ((event: SnowLumaEvent) => void) | undefined
 
     constructor(deps: RouterDeps) {
         this.sender = deps.sender
         this.roles = deps.roles
         this.gate = deps.gate
         this.logger = deps.logger.child('router')
+        this.onEvent = deps.onEvent
         this.refuser = new PermissionRefuser(deps.sender, this.logger)
     }
 
@@ -122,6 +125,8 @@ export class Router {
     ) => {
         if (!this.accepting) return
 
+        this.emitEvent(event)
+
         const run = this.handleEvent(event, sdkContext, next)
         this.active.add(run)
 
@@ -132,6 +137,16 @@ export class Router {
         }
     }
 
+    private emitEvent(event: SnowLumaEvent): void {
+        if (!this.onEvent) return
+
+        try {
+            this.onEvent(event)
+        } catch (error) {
+            this.logger.error('event tap failed', error)
+        }
+    }
+
     private async handleEvent(
         event: SnowLumaEvent,
         sdkContext: SnowLumaEventContextWithQuote,
@@ -180,7 +195,8 @@ export class Router {
                         try {
                             const parsed =
                                 found.registration.paramsParser.parse(
-                                    found.match.rest
+                                    found.match.rest,
+                                    event
                                 )
 
                             args = parsed.args

package/src/core/index.ts

@@ -6,6 +6,7 @@ export type {
     PluginEnvelope,
     PluginGroups,
     RolesConfig,
+    WebUiConfig,
 } from './config/schema.js'
 export type { TaskQueue } from './dispatch/task-queue.js'
 export type { Logger, LogLevel } from './logging/logger.js'
@@ -50,8 +51,10 @@ export type {
 } from './plugin/types.js'
 export type { Permission } from './security/permission.js'
 export type {
+    SessionListOptions,
     SessionMessage,
     SessionRole,
     SessionState,
     SessionStore,
+    SessionSummary,
 } from './storage/session.js'