@jsbot-tellus/core 2.4.0 → 2.5.1

package/src/core/plugin/install-dir.ts

@@ -1,427 +1,19 @@
-import { randomUUID } from 'node:crypto'
-import { readFileSync } from 'node:fs'
-import {
-    mkdir,
-    readFile,
-    realpath,
-    rename,
-    rm,
-    stat,
-    symlink,
-    writeFile,
-} from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-export const CORE_PACKAGE_NAME = '@jsbot-tellus/core'
-export const INSTALL_STATE_FILE = '.jsbot-installed.json'
-export const VALIDATE_SCRIPT_FILE = 'validate.mjs'
-
-export interface InstalledPackageRecord {
-    spec: string
-    version: string
-    pluginIds: string[]
-    dependencies: Record<string, string[]>
-    installedAt: string
-    /** Directory name under the plugins root. */
-    dir: string
-}
-
-export interface InstallState {
-    version: 2
-    packages: Record<string, InstalledPackageRecord>
-}
-
-export class InstallStateError extends Error {
-    constructor(message: string, options?: ErrorOptions) {
-        super(message, options)
-        this.name = 'InstallStateError'
-    }
-}
-
-export function packageDirectoryName(name: string): string {
-    return name.startsWith('@') ? name.replace('/', '__') : name
-}
-
-export async function readJsonFile(path: string): Promise<unknown> {
-    try {
-        return JSON.parse(await readFile(path, 'utf8'))
-    } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
-
-        throw error
-    }
-}
-
-export async function readPackageVersion(
-    directory: string
-): Promise<string | undefined> {
-    const manifest = await readJsonFile(join(directory, 'package.json')).catch(
-        () => undefined
-    )
-
-    if (typeof manifest !== 'object' || manifest === null) return undefined
-
-    const version = (manifest as Record<string, unknown>)['version']
-
-    return typeof version === 'string' ? version : undefined
-}
-
-function isSafeDirectoryName(value: string): boolean {
-    return (
-        value.length > 0 &&
-        value !== '.' &&
-        value !== '..' &&
-        !value.includes('/') &&
-        !value.includes('\\')
-    )
-}
-
-export async function readInstallState(dir: string): Promise<InstallState> {
-    const path = join(dir, INSTALL_STATE_FILE)
-    let value: unknown
-
-    try {
-        value = await readJsonFile(path)
-    } catch (error) {
-        throw new InstallStateError(`安装状态文件无法解析: ${path}`, {
-            cause: error,
-        })
-    }
-
-    if (value === undefined) {
-        return { version: 2, packages: {} }
-    }
-
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new InstallStateError(`安装状态文件格式无效: ${path}`)
-    }
-
-    if ((value as Record<string, unknown>)['version'] !== 2) {
-        throw new InstallStateError(`不支持的安装状态版本，请检查 ${path}`)
-    }
-
-    const packages = (value as Record<string, unknown>)['packages']
-
-    if (
-        typeof packages !== 'object' ||
-        packages === null ||
-        Array.isArray(packages)
-    ) {
-        throw new InstallStateError(`安装状态 packages 字段无效: ${path}`)
-    }
-
-    const result: Record<string, InstalledPackageRecord> = {}
-    const directories = new Set<string>()
-
-    for (const [name, rawRecord] of Object.entries(packages)) {
-        if (
-            typeof rawRecord !== 'object' ||
-            rawRecord === null ||
-            Array.isArray(rawRecord)
-        ) {
-            throw new InstallStateError(`安装状态记录无效: ${name}`)
-        }
-
-        const record = rawRecord as Record<string, unknown>
-        const pluginIds = record['pluginIds']
-        const dependencies = record['dependencies']
-        const directory = record['dir']
-
-        if (
-            typeof record['spec'] !== 'string' ||
-            typeof record['version'] !== 'string' ||
-            typeof record['installedAt'] !== 'string' ||
-            typeof directory !== 'string' ||
-            !isSafeDirectoryName(directory) ||
-            !Array.isArray(pluginIds) ||
-            pluginIds.some((item) => typeof item !== 'string')
-        ) {
-            throw new InstallStateError(`安装状态记录不完整: ${name}`)
-        }
-
-        if (directories.has(directory)) {
-            throw new InstallStateError(
-                `安装状态存在重复的插件目录: ${directory}`
-            )
-        }
-
-        directories.add(directory)
-
-        if (
-            typeof dependencies !== 'object' ||
-            dependencies === null ||
-            Array.isArray(dependencies)
-        ) {
-            throw new InstallStateError(`安装状态依赖字段无效: ${name}`)
-        }
-
-        const parsedDependencies: Record<string, string[]> = {}
-
-        for (const [id, list] of Object.entries(dependencies)) {
-            if (
-                !Array.isArray(list) ||
-                list.some((item) => typeof item !== 'string')
-            ) {
-                throw new InstallStateError(
-                    `安装状态依赖记录无效: ${name}.${id}`
-                )
-            }
-
-            parsedDependencies[id] = [...list]
-        }
-
-        result[name] = {
-            spec: record['spec'],
-            version: record['version'],
-            pluginIds: [...pluginIds],
-            dependencies: parsedDependencies,
-            installedAt: record['installedAt'],
-            dir: directory,
-        }
-    }
-
-    return { version: 2, packages: result }
-}
-
-export async function writeInstallState(
-    dir: string,
-    state: InstallState
-): Promise<void> {
-    const sorted: InstallState = { version: 2, packages: {} }
-
-    for (const name of Object.keys(state.packages).sort()) {
-        const record = state.packages[name]
-        if (!record) continue
-        sorted.packages[name] = record
-    }
-
-    const path = join(dir, INSTALL_STATE_FILE)
-    const temporary = `${path}.${randomUUID()}.tmp`
-
-    try {
-        await writeFile(
-            temporary,
-            `${JSON.stringify(sorted, null, 4)}\n`,
-            'utf8'
-        )
-        await rename(temporary, path)
-    } catch (error) {
-        await rm(temporary, { force: true }).catch(() => undefined)
-        throw error
-    }
-}
-
-export function corePackageRoot(): string {
-    let current = dirname(fileURLToPath(import.meta.url))
-
-    for (;;) {
-        try {
-            const manifest = JSON.parse(
-                readFileSync(join(current, 'package.json'), 'utf8')
-            ) as Record<string, unknown>
-
-            if (manifest['name'] === CORE_PACKAGE_NAME) return current
-        } catch {
-            // keep walking up
-        }
-
-        const parent = dirname(current)
-
-        if (parent === current) {
-            throw new Error(`cannot locate ${CORE_PACKAGE_NAME} package root`)
-        }
-
-        current = parent
-    }
-}
-
-export async function ensureCoreLink(dir: string): Promise<void> {
-    const target = corePackageRoot()
-    const link = join(dir, 'node_modules', '@jsbot-tellus', 'core')
-
-    await mkdir(dirname(link), { recursive: true })
-
-    const existing = await realpath(link).catch(() => null)
-
-    if (existing !== null) {
-        const resolvedTarget = await realpath(target).catch(() => target)
-
-        if (existing === resolvedTarget) return
-
-        await rm(link, { recursive: true, force: true })
-    }
-
-    await symlink(
-        target,
-        link,
-        process.platform === 'win32' ? 'junction' : 'dir'
-    )
-}
-
-export async function pathExists(path: string): Promise<boolean> {
-    return (await stat(path).catch(() => null)) !== null
-}
-
-export async function ensureInstallRoot(root: string): Promise<void> {
-    await mkdir(root, { recursive: true })
-    await mkdir(join(root, '.jsbot'), { recursive: true })
-    await writeFile(
-        join(root, '.jsbot', VALIDATE_SCRIPT_FILE),
-        VALIDATE_SCRIPT,
-        'utf8'
-    )
-}
-
-const VALIDATE_SCRIPT = `import { readdir } from 'node:fs/promises'
-import { extname, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-const directory = process.argv[2]
-
-if (!directory) {
-    console.error('missing plugin directory')
-    process.exit(2)
-}
-
-const extensions = new Set(['.js', '.mjs', '.cjs'])
-
-async function filesIn(directory) {
-    const entries = await readdir(directory, { withFileTypes: true })
-    entries.sort((a, b) => a.name.localeCompare(b.name))
-
-    const files = []
-
-    for (const entry of entries) {
-        if (entry.name.startsWith('.')) continue
-
-        const path = join(directory, entry.name)
-
-        if (entry.isDirectory()) {
-            if (entry.name === 'node_modules') continue
-            files.push(...(await filesIn(path)))
-            continue
-        }
-
-        if (
-            entry.isFile() &&
-            extensions.has(extname(entry.name)) &&
-            !/\\.d\\.(ts|mts|cts)$/.test(entry.name)
-        ) {
-            files.push(path)
-        }
-    }
-
-    return files
-}
-
-function isPlugin(value) {
-    if (typeof value !== 'object' || value === null) return false
-    if (!('manifest' in value) || !('setup' in value)) return false
-
-    const manifest = value.manifest
-
-    if (
-        typeof manifest !== 'object' ||
-        manifest === null ||
-        typeof manifest.id !== 'string' ||
-        typeof manifest.configSchema !== 'object' ||
-        manifest.configSchema === null ||
-        typeof manifest.configSchema.safeParse !== 'function' ||
-        typeof value.setup !== 'function'
-    ) {
-        return false
-    }
-
-    if (
-        manifest.dependencies !== undefined &&
-        (!Array.isArray(manifest.dependencies) ||
-            manifest.dependencies.some((item) => typeof item !== 'string'))
-    ) {
-        return false
-    }
-
-    return true
-}
-
-function collect(value, result) {
-    if (Array.isArray(value)) {
-        for (const item of value) collect(item, result)
-        return
-    }
-
-    if (isPlugin(value)) {
-        result.push(value)
-        return
-    }
-
-    if (
-        typeof value === 'object' &&
-        value !== null &&
-        'plugins' in value &&
-        Array.isArray(value.plugins)
-    ) {
-        for (const item of value.plugins) collect(item, result)
-    }
-}
-
-const files = await filesIn(directory).catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error))
-    process.exit(3)
-})
-
-if (files.length === 0) {
-    console.error('插件 dist 目录中没有可加载的文件')
-    process.exit(4)
-}
-
-const found = []
-const invalid = []
-
-for (const file of files) {
-    let imported
-
-    try {
-        imported = await import(pathToFileURL(file).href)
-    } catch (error) {
-        invalid.push(
-            \`failed to import \${file}: \${error instanceof Error ? error.message : String(error)}\`
-        )
-        continue
-    }
-
-    if (typeof imported !== 'object' || imported === null) continue
-
-    for (const candidate of [imported.default, imported.plugin, imported.plugins]) {
-        collect(candidate, found)
-    }
-}
-
-const unique = found.filter((plugin, index) => found.indexOf(plugin) === index)
-
-if (unique.length === 0) {
-    console.error(
-        invalid[0] ??
-            'package does not export a JsBot plugin (default / plugin / plugins)'
-    )
-    process.exit(5)
-}
-
-console.log(
-    '__JSBOT_PLUGIN__' +
-        JSON.stringify(
-            unique.map((plugin) => ({
-                id: plugin.manifest.id,
-                version:
-                    typeof plugin.manifest.version === 'string'
-                        ? plugin.manifest.version
-                        : '0.0.0',
-                dependencies: Array.isArray(plugin.manifest.dependencies)
-                    ? plugin.manifest.dependencies.filter(
-                          (item) => typeof item === 'string'
-                      )
-                    : [],
-            }))
-        )
-)
-`
+export {
+    CORE_PACKAGE_NAME,
+    corePackageRoot,
+    ensureCoreLink,
+    ensureInstallRoot,
+    packageDirectoryName,
+    pathExists,
+} from './install/paths.js'
+export {
+    INSTALL_STATE_FILE,
+    InstallStateError,
+    readInstallState,
+    readJsonFile,
+    readPackageVersion,
+    writeInstallState,
+    type InstalledPackageRecord,
+    type InstallState,
+} from './install/state.js'
+export { VALIDATE_SCRIPT_FILE } from './install/validate-script.js'

package/src/core/plugin/installer/checks.ts

@@ -0,0 +1,137 @@
+import type { InstalledPackageRecord, InstallState } from '../install-dir.js'
+import { pathExists } from '../install-dir.js'
+import type { ValidatedPlugin } from '../install-validate.js'
+import { ID_PATTERN, InstallerError } from './support.js'
+
+export function checkPlugins(
+    packageName: string,
+    plugins: ValidatedPlugin[],
+    state: InstallState,
+    reservedIds: () => ReadonlySet<string>
+): void {
+    const ownIds = new Set(state.packages[packageName]?.pluginIds ?? [])
+    const ids = new Set<string>()
+    const taken = new Set<string>()
+
+    for (const id of reservedIds()) {
+        if (!ownIds.has(id)) taken.add(id)
+    }
+
+    for (const [name, record] of Object.entries(state.packages)) {
+        if (name === packageName) continue
+
+        for (const id of record.pluginIds) taken.add(id)
+    }
+
+    for (const plugin of plugins) {
+        if (!ID_PATTERN.test(plugin.id)) {
+            throw new InstallerError(`插件 id 无效: ${plugin.id}`)
+        }
+
+        if (ids.has(plugin.id)) {
+            throw new InstallerError(`插件 id 重复: ${plugin.id}`)
+        }
+
+        if (taken.has(plugin.id)) {
+            throw new InstallerError(
+                `插件 id 已被占用: ${plugin.id}（内置插件或其他已安装包）`
+            )
+        }
+
+        ids.add(plugin.id)
+    }
+
+    const graph = new Map<string, string[]>()
+
+    for (const [name, record] of Object.entries(state.packages)) {
+        if (name === packageName) continue
+
+        for (const id of record.pluginIds) {
+            graph.set(id, record.dependencies[id] ?? [])
+        }
+    }
+
+    for (const plugin of plugins) {
+        graph.set(plugin.id, plugin.dependencies)
+    }
+
+    const reserved = reservedIds()
+    const available = new Set(graph.keys())
+
+    for (const id of reserved) {
+        if (!ownIds.has(id)) available.add(id)
+    }
+
+    for (const [id, dependencies] of graph) {
+        for (const dependency of dependencies) {
+            if (!available.has(dependency)) {
+                throw new InstallerError(
+                    `插件 ${id} 依赖未加载的插件: ${dependency}`
+                )
+            }
+        }
+    }
+
+    const visiting = new Set<string>()
+    const visited = new Set<string>()
+
+    const visit = (id: string): void => {
+        if (visited.has(id)) return
+
+        if (visiting.has(id)) {
+            throw new InstallerError(`插件依赖存在循环: ${id}`)
+        }
+
+        visiting.add(id)
+
+        for (const dependency of graph.get(id) ?? []) {
+            if (graph.has(dependency)) visit(dependency)
+        }
+
+        visiting.delete(id)
+        visited.add(id)
+    }
+
+    for (const id of graph.keys()) visit(id)
+}
+
+export function resolveTarget(target: string, state: InstallState): string {
+    const value = target.trim()
+
+    if (value.length === 0) {
+        throw new InstallerError('请提供包名或插件 id')
+    }
+
+    if (state.packages[value] !== undefined) return value
+
+    for (const [name, record] of Object.entries(state.packages)) {
+        if (record.pluginIds.includes(value)) return name
+    }
+
+    throw new InstallerError(`未找到已安装的插件包: ${value}`)
+}
+
+export async function assertTargetAvailable(
+    state: InstallState,
+    packageName: string,
+    directory: string,
+    target: string,
+    previous: InstalledPackageRecord | undefined
+): Promise<void> {
+    for (const [name, record] of Object.entries(state.packages)) {
+        if (name === packageName) continue
+        if (record.dir !== directory) continue
+
+        throw new InstallerError(
+            `插件目录已被其它已安装包使用: ${record.dir}（${name}）`
+        )
+    }
+
+    if (previous !== undefined) return
+
+    if (await pathExists(target)) {
+        throw new InstallerError(
+            `安装目录已存在且不是由安装器管理: ${target}。请先移除该本地插件或为其改名。`
+        )
+    }
+}

package/src/core/plugin/installer/support.ts

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import type { InstallerConfig } from '../../config/schema.js'
+import type { Logger } from '../../logging/logger.js'
+import { packageDirectoryName } from '../install-dir.js'
+import type { PackageValidator } from '../install-validate.js'
+import type { NpmRunner } from '../npm-runner.js'
+import {
+    isPackageAllowed,
+    parsePackageSpec,
+    PackageSpecError,
+    type PackageSpec,
+} from '../spec.js'
+import type { PluginInstaller } from '../types.js'
+
+export class InstallerError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options)
+        this.name = 'InstallerError'
+    }
+}
+
+export interface InstallerOptions {
+    /** Plugins root. Installed packages are placed in subdirectories here. */
+    dir: string
+    config: InstallerConfig
+    logger: Logger
+    runner?: NpmRunner | undefined
+    validate?: PackageValidator | undefined
+    reservedIds?: (() => ReadonlySet<string>) | undefined
+    configuredPluginIds?: (() => ReadonlySet<string>) | undefined
+    now?: (() => Date) | undefined
+}
+
+export const ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i
+export const NPM_FLAGS = ['--no-audit', '--no-fund', '--loglevel=error']
+export const STAGING_MANIFEST = {
+    name: '@jsbot-tellus/plugin-staging',
+    private: true,
+    version: '0.0.0',
+    type: 'module',
+}
+
+export function messageOf(error: unknown): string {
+    return error instanceof Error ? error.message : String(error)
+}
+
+export function asInstallerError(error: unknown): InstallerError {
+    if (error instanceof InstallerError) return error
+
+    if (error instanceof PackageSpecError) {
+        return new InstallerError(error.message, { cause: error })
+    }
+
+    return new InstallerError(messageOf(error), { cause: error })
+}
+
+export function installDirectoryName(
+    packageName: string,
+    pluginIds: readonly string[]
+): string {
+    const only = pluginIds.length === 1 ? pluginIds[0] : undefined
+
+    return only ?? packageDirectoryName(packageName)
+}
+
+export function parseInstallerSpec(
+    spec: string,
+    allowedPackages: string[]
+): PackageSpec {
+    const parsed = parsePackageSpec(spec)
+
+    if (!isPackageAllowed(parsed.name, allowedPackages)) {
+        throw new InstallerError(`包不在允许列表: ${parsed.name}`)
+    }
+
+    return parsed
+}
+
+export function temporaryPath(dir: string, kind: 'staging' | 'backup'): string {
+    return join(dir, `.${kind}-${randomUUID()}`)
+}
+
+export function assertInstallerEnabled(enabled: boolean): void {
+    if (!enabled) {
+        throw new InstallerError(
+            '插件安装功能未启用（installer.enabled=false）'
+        )
+    }
+}
+
+export function createTaskSerializer(): <T>(
+    task: () => Promise<T>
+) => Promise<T> {
+    let tail: Promise<unknown> = Promise.resolve()
+
+    return <T>(task: () => Promise<T>): Promise<T> => {
+        const run = tail.then(task, task)
+
+        tail = run.then(
+            () => undefined,
+            () => undefined
+        )
+
+        return run
+    }
+}
+
+export function createDisabledInstaller(): PluginInstaller {
+    const fail = (): Promise<never> =>
+        Promise.reject(new InstallerError('插件安装功能未启用'))
+
+    return {
+        enabled: false,
+        list: () => Promise.resolve([]),
+        install: fail,
+        remove: fail,
+        update: fail,
+    }
+}