@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/platform/notification.ts

@@ -0,0 +1,108 @@
+/*
+ * 系统通知。
+ * Windows 走 PowerShell 的 WinRT toast，脚本内容经 -EncodedCommand 传递；
+ * WSL 下优先调用 powershell.exe，其余平台使用各自的通知命令。
+ */
+
+import { describeError, powershellArgs, runCommand } from "./exec.ts"
+import { isWsl, platform, type PlatformName } from "./os.ts"
+
+export interface NotifyOptions {
+    readonly title: string
+    readonly body?: string
+}
+
+export interface NotifyCommand {
+    readonly command: string
+    readonly args: readonly string[]
+    readonly env?: Readonly<Record<string, string>>
+}
+
+const MACOS_SCRIPT =
+    'display notification (system attribute "WELLSPRING_NOTIFY_BODY") with title (system attribute "WELLSPRING_NOTIFY_TITLE")'
+
+/** PowerShell 单引号字符串，内部单引号翻倍 */
+function psQuote(value: string): string {
+    return `'${value.replace(/'/g, "''")}'`
+}
+
+function powershellToast(title: string, body: string): string[] {
+    const script = [
+        "$ErrorActionPreference = 'Stop'",
+        "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null",
+        "$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
+        '$texts = $template.GetElementsByTagName("text")',
+        `$texts.Item(0).AppendChild($template.CreateTextNode(${psQuote(title)})) > $null`,
+        `$texts.Item(1).AppendChild($template.CreateTextNode(${psQuote(body)})) > $null`,
+        "$toast = [Windows.UI.Notifications.ToastNotification]::new($template)",
+        '[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Wellspring").Show($toast)',
+    ].join("\n")
+    return powershellArgs(script)
+}
+
+function normalize(options: NotifyOptions): { title: string; body: string } {
+    const title = options.title.trim()
+    if (title === "") {
+        throw new Error("通知标题为空")
+    }
+    return { title, body: options.body ?? "" }
+}
+
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试 */
+export function buildNotifyCommands(
+    options: NotifyOptions,
+    targetPlatform: PlatformName = platform,
+    inWsl: boolean = isWsl,
+): NotifyCommand[] {
+    const { title, body } = normalize(options)
+
+    if (targetPlatform === "windows") {
+        return [{ command: "powershell", args: powershellToast(title, body) }]
+    }
+
+    if (targetPlatform === "macos") {
+        return [
+            {
+                command: "osascript",
+                args: ["-e", MACOS_SCRIPT],
+                env: { WELLSPRING_NOTIFY_TITLE: title, WELLSPRING_NOTIFY_BODY: body },
+            },
+        ]
+    }
+
+    if (targetPlatform === "android") {
+        const args = ["--title", title]
+        if (body !== "") {
+            args.push("--content", body)
+        }
+        return [{ command: "termux-notification", args }]
+    }
+
+    const candidates: NotifyCommand[] = []
+    if (inWsl) {
+        // WSL 没有桌面通知守护进程，转到 Windows 侧显示
+        candidates.push({ command: "powershell.exe", args: powershellToast(title, body) })
+    }
+    const args = ["-a", "wellspring", "--", title]
+    if (body !== "") {
+        args.push(body)
+    }
+    candidates.push({ command: "notify-send", args })
+    return candidates
+}
+
+/** 发送系统通知。全部候选失败时抛出聚合错误 */
+export async function notify(options: NotifyOptions): Promise<void> {
+    const failures: string[] = []
+    for (const candidate of buildNotifyCommands(options)) {
+        try {
+            const env =
+                candidate.env === undefined ? undefined : { ...process.env, ...candidate.env }
+            await runCommand(candidate.command, candidate.args, { env })
+            return
+        } catch (error) {
+            failures.push(`${candidate.command}: ${describeError(error)}`)
+        }
+    }
+    throw new Error(`通知发送失败：${failures.join("；")}`)
+}

package/src/platform/open-external.ts

@@ -0,0 +1,132 @@
+/*
+ * 用系统默认程序打开 URL 或本地路径。
+ * target 可能来自外部输入，须校验：以 "-" 开头会被 open / cmd start 视为参数，协议限定白名单。
+ */
+
+import { spawn } from "node:child_process"
+import { isAbsolute } from "node:path"
+
+import { describeError } from "./exec.ts"
+import { isTermux, isWsl, platform, type PlatformName } from "./os.ts"
+
+/** 候选启动命令 */
+export interface OpenCommand {
+    readonly command: string
+    readonly args: readonly string[]
+}
+
+/** 允许的协议 */
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:", "file:"])
+
+interface NormalizedTarget {
+    readonly target: string
+    readonly isUrl: boolean
+}
+
+/** 绝对路径原样返回；其余须为白名单协议 URL。不合法时抛出异常 */
+function normalizeTarget(input: string): NormalizedTarget {
+    const target = input.trim()
+    if (target === "") {
+        throw new Error("打开目标为空值")
+    }
+    // 控制字符（含换行）会破坏命令行语义
+    if (/[\u0000-\u001f\u007f]/.test(target)) {
+        throw new Error("打开目标包含控制字符")
+    }
+    if (target.startsWith("-")) {
+        throw new Error(`打开目标不能以 "-" 开头：${target}`)
+    }
+    // 本地路径；Windows 的 "C:\\..." 亦归此类
+    if (isAbsolute(target)) {
+        return { target, isUrl: false }
+    }
+
+    let parsed: URL
+    try {
+        parsed = new URL(target)
+    } catch {
+        throw new Error(`目标既非绝对路径也非合法 URL：${target}`)
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`不允许的协议：${parsed.protocol}`)
+    }
+    return { target: parsed.href, isUrl: true }
+}
+
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试各系统的构造结果 */
+export function buildOpenCommands(
+    rawTarget: string,
+    targetPlatform: PlatformName = platform,
+    inWsl: boolean = isWsl,
+    inTermux: boolean = isTermux,
+): OpenCommand[] {
+    const { target, isUrl } = normalizeTarget(rawTarget)
+
+    if (targetPlatform === "windows") {
+        // 第二个参数为 start 的窗口标题占位；缺失时带引号的路径会被当作标题
+        return [{ command: "cmd", args: ["/c", "start", "", target] }]
+    }
+
+    if (targetPlatform === "macos") {
+        return [{ command: "open", args: [target] }]
+    }
+
+    if (targetPlatform === "android") {
+        const candidates: OpenCommand[] = []
+        if (inTermux) {
+            candidates.push({ command: "termux-open", args: [target] })
+        }
+        candidates.push({ command: "xdg-open", args: [target] })
+        // am 只能打开 URI，本地路径没有对应的 content:// 地址
+        if (isUrl) {
+            candidates.push({
+                command: "am",
+                args: ["start", "-a", "android.intent.action.VIEW", "-d", target],
+            })
+        }
+        return candidates
+    }
+
+    const candidates: OpenCommand[] = []
+    if (inWsl) {
+        // WSL 下 xdg-open 常无效，优先 wslview（wslu），其次 explorer.exe
+        candidates.push({ command: "wslview", args: [target] })
+        candidates.push({ command: "explorer.exe", args: [target] })
+    }
+    candidates.push({ command: "xdg-open", args: [target] })
+    candidates.push({ command: "gio", args: ["open", target] })
+    return candidates
+}
+
+function spawnDetached(command: string, args: readonly string[]): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        })
+        child.once("error", reject)
+        child.once("spawn", () => {
+            // 不等待退出：浏览器与文件管理器均为长驻进程
+            child.unref()
+            resolve()
+        })
+    })
+}
+
+/** 依次尝试候选命令，全部失败时抛出聚合错误 */
+export async function openExternal(rawTarget: string): Promise<void> {
+    const { target } = normalizeTarget(rawTarget)
+    const failures: string[] = []
+
+    for (const candidate of buildOpenCommands(target)) {
+        try {
+            await spawnDetached(candidate.command, candidate.args)
+            return
+        } catch (error) {
+            failures.push(`${candidate.command}: ${describeError(error)}`)
+        }
+    }
+
+    throw new Error(`无法打开 ${target}：已尝试 ${failures.join("；")}`)
+}

package/src/platform/os.ts

@@ -0,0 +1,101 @@
+/*
+ * 平台识别。
+ * 本模块是唯一读取 process.platform 的位置。
+ */
+
+import { homedir } from "node:os"
+
+/** 业务侧平台名，不使用 Node 的 win32 / darwin / linux 原始值 */
+export type PlatformName = "windows" | "macos" | "linux" | "android"
+
+/** Termux 等 Android 用户态 Node 报告 linux，用 Android 环境变量识别 */
+function isAndroidEnv(env: NodeJS.ProcessEnv): boolean {
+    const has = (name: string): boolean => {
+        const value = env[name]
+        return value !== undefined && value.trim() !== ""
+    }
+    return has("ANDROID_ROOT") || has("ANDROID_DATA") || has("TERMUX_VERSION")
+}
+
+/** 平台归一化。参数可注入，供测试覆盖各平台 */
+export function detectPlatform(
+    nodePlatform: NodeJS.Platform = process.platform,
+    env: NodeJS.ProcessEnv = process.env,
+): PlatformName {
+    switch (nodePlatform) {
+        case "win32":
+            return "windows"
+        case "darwin":
+            return "macos"
+        case "android":
+            return "android"
+        default:
+            return isAndroidEnv(env) ? "android" : "linux"
+    }
+}
+
+export const platform: PlatformName = detectPlatform()
+export const isWindows: boolean = platform === "windows"
+export const isMacOS: boolean = platform === "macos"
+export const isLinux: boolean = platform === "linux"
+export const isAndroid: boolean = platform === "android"
+/** POSIX 权限与路径语义可用的平台，含 Android */
+export const isPosix: boolean = platform !== "windows"
+
+function detectWsl(): boolean {
+    if (platform !== "linux") {
+        return false
+    }
+    // WSL 会注入 WSL_DISTRO_NAME / WSL_INTEROP，该环境下调用外部程序的行为与原生 Linux 不同
+    return process.env["WSL_DISTRO_NAME"] !== undefined || process.env["WSL_INTEROP"] !== undefined
+}
+
+export const isWsl: boolean = detectWsl()
+
+/** Android 上的 Termux 用户态 */
+export const isTermux: boolean =
+    isAndroid &&
+    (readEnv("TERMUX_VERSION") !== undefined ||
+        (readEnv("PREFIX")?.includes("com.termux") ?? false))
+
+/** 读取环境变量，空串按未设置处理。Windows 下变量名大小写不敏感 */
+export function readEnv(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+    const direct = env[name]
+    if (direct !== undefined) {
+        const value = direct.trim()
+        return value === "" ? undefined : value
+    }
+    if (!isWindows) {
+        return undefined
+    }
+    // Windows 环境变量名不区分大小写
+    const lower = name.toLowerCase()
+    const key = Object.keys(env).find((item) => item.toLowerCase() === lower)
+    const value = key === undefined ? undefined : env[key]?.trim()
+    return value === undefined || value === "" ? undefined : value
+}
+
+/** HOME 优先，其次 USERPROFILE 与系统用户目录；Android 沙箱可能三者皆无 */
+export function homeDir(env: NodeJS.ProcessEnv = process.env): string {
+    const fromEnv = readEnv("HOME", env) ?? readEnv("USERPROFILE", env)
+    if (fromEnv !== undefined) {
+        return fromEnv
+    }
+    try {
+        const home = homedir()
+        if (home !== "") {
+            return home
+        }
+    } catch {
+        // 无 passwd 条目时回落
+    }
+    return process.cwd()
+}
+
+/** Windows 可执行文件带 .exe 后缀 */
+export function executableName(name: string): string {
+    if (!isWindows || name.toLowerCase().endsWith(".exe")) {
+        return name
+    }
+    return `${name}.exe`
+}

package/src/platform/path.ts

@@ -0,0 +1,214 @@
+/*
+ * 目录解析。
+ * 根目录：config（配置与凭据）、data（持久数据）、cache（可再生成）、log（日志）。
+ * 优先级：initPaths 显式覆盖 > WELLSPRING_*_DIR > WELLSPRING_HOME 便携模式 > 平台默认。
+ * 仅解析路径，不创建目录；创建见 file.ts 的 ensureDirs。
+ */
+
+import { isAbsolute, join, normalize } from "node:path"
+
+import { homeDir, platform, readEnv, type PlatformName } from "./os.ts"
+
+/** 各平台统一使用的目录名 */
+export const APP_DIR_NAME = "wellspring"
+
+/** 四个根目录 */
+export interface PathRoots {
+    readonly configDir: string
+    readonly dataDir: string
+    readonly cacheDir: string
+    readonly logDir: string
+}
+
+/** 显式覆盖，通常来自 CLI 参数。相对路径按当前工作目录解析 */
+export interface PathOverrides {
+    readonly configDir?: string
+    readonly dataDir?: string
+    readonly cacheDir?: string
+    readonly logDir?: string
+}
+
+/** 取值来源，用于诊断 */
+export type PathSource = "override" | "env" | "portable-home" | "os-default"
+
+export interface ResolvedPaths extends PathRoots {
+    readonly sources: Readonly<Record<keyof PathRoots, PathSource>>
+}
+
+const ROOT_KEYS = ["configDir", "dataDir", "cacheDir", "logDir"] as const
+type RootKey = (typeof ROOT_KEYS)[number]
+
+const ENV_NAMES: Readonly<Record<RootKey, string>> = {
+    configDir: "WELLSPRING_CONFIG_DIR",
+    dataDir: "WELLSPRING_DATA_DIR",
+    cacheDir: "WELLSPRING_CACHE_DIR",
+    logDir: "WELLSPRING_LOG_DIR",
+}
+
+const ROOT_LABELS: Readonly<Record<RootKey, string>> = {
+    configDir: "config",
+    dataDir: "data",
+    cacheDir: "cache",
+    logDir: "log",
+}
+
+/** 是否 Termux 用户态：目录沿用 XDG，HOME 可用 */
+function isTermuxEnv(env: NodeJS.ProcessEnv): boolean {
+    return (
+        readEnv("TERMUX_VERSION", env) !== undefined ||
+        (readEnv("PREFIX", env)?.includes("com.termux") ?? false)
+    )
+}
+
+function xdgRoots(env: NodeJS.ProcessEnv, home: string): PathRoots {
+    return {
+        configDir: join(readEnv("XDG_CONFIG_HOME", env) ?? join(home, ".config"), APP_DIR_NAME),
+        dataDir: join(readEnv("XDG_DATA_HOME", env) ?? join(home, ".local", "share"), APP_DIR_NAME),
+        cacheDir: join(readEnv("XDG_CACHE_HOME", env) ?? join(home, ".cache"), APP_DIR_NAME),
+        logDir: join(
+            readEnv("XDG_STATE_HOME", env) ?? join(home, ".local", "state"),
+            APP_DIR_NAME,
+            "logs",
+        ),
+    }
+}
+
+/*
+ * Android 应用沙箱：HOME 通常指向应用私有 files 目录。
+ * 未设置 HOME 时依赖 WELLSPRING_HOME；两者皆无则使用系统用户目录。
+ */
+function androidAppRoots(env: NodeJS.ProcessEnv, home: string): PathRoots {
+    const base = readEnv("HOME", env) ?? home
+    return {
+        configDir: join(base, "config"),
+        dataDir: join(base, "data"),
+        cacheDir: join(base, "cache"),
+        logDir: join(base, "logs"),
+    }
+}
+
+/** 平台默认根目录。参数可注入，供测试覆盖各平台 */
+export function defaultRoots(
+    platformName: PlatformName,
+    env: NodeJS.ProcessEnv,
+    home: string,
+): PathRoots {
+    switch (platformName) {
+        case "windows": {
+            const roaming = readEnv("APPDATA", env) ?? join(home, "AppData", "Roaming")
+            const local = readEnv("LOCALAPPDATA", env) ?? join(home, "AppData", "Local")
+            return {
+                configDir: join(roaming, APP_DIR_NAME),
+                dataDir: join(local, APP_DIR_NAME),
+                // Windows 无独立缓存目录约定，缓存与日志置于 data 下
+                cacheDir: join(local, APP_DIR_NAME, "cache"),
+                logDir: join(local, APP_DIR_NAME, "logs"),
+            }
+        }
+        case "macos": {
+            // macOS 惯例：配置与数据同放 Application Support，缓存与日志各自独立
+            const support = join(home, "Library", "Application Support", APP_DIR_NAME)
+            return {
+                configDir: support,
+                dataDir: support,
+                cacheDir: join(home, "Library", "Caches", APP_DIR_NAME),
+                logDir: join(home, "Library", "Logs", APP_DIR_NAME),
+            }
+        }
+        case "android":
+            return isTermuxEnv(env) ? xdgRoots(env, home) : androidAppRoots(env, home)
+        default:
+            return xdgRoots(env, home)
+    }
+}
+
+/** 便携模式：所有数据落在同一个根下 */
+function portableRoots(home: string): PathRoots {
+    return {
+        configDir: join(home, "config"),
+        dataDir: join(home, "data"),
+        cacheDir: join(home, "cache"),
+        logDir: join(home, "logs"),
+    }
+}
+
+function expandTilde(input: string, env: NodeJS.ProcessEnv): string {
+    if (input === "~") {
+        return homeDir(env)
+    }
+    if (input.startsWith("~/") || input.startsWith("~\\")) {
+        return join(homeDir(env), input.slice(2))
+    }
+    return input
+}
+
+function toAbsolute(input: string, env: NodeJS.ProcessEnv): string {
+    const expanded = expandTilde(input, env)
+    return normalize(isAbsolute(expanded) ? expanded : join(process.cwd(), expanded))
+}
+
+let cached: ResolvedPaths | null = null
+
+/** 解析并缓存。重复调用会按最新参数与环境变量重新解析 */
+export function initPaths(
+    overrides: PathOverrides = {},
+    env: NodeJS.ProcessEnv = process.env,
+): ResolvedPaths {
+    const home = homeDir(env)
+    const portableHome = readEnv("WELLSPRING_HOME", env)
+    const defaults =
+        portableHome === undefined
+            ? defaultRoots(platform, env, home)
+            : portableRoots(toAbsolute(portableHome, env))
+    const baseSource: PathSource = portableHome === undefined ? "os-default" : "portable-home"
+
+    const roots: Record<RootKey, string> = {
+        configDir: "",
+        dataDir: "",
+        cacheDir: "",
+        logDir: "",
+    }
+    const sources: Record<RootKey, PathSource> = {
+        configDir: baseSource,
+        dataDir: baseSource,
+        cacheDir: baseSource,
+        logDir: baseSource,
+    }
+
+    for (const key of ROOT_KEYS) {
+        const override = overrides[key]
+        if (override !== undefined && override.trim() !== "") {
+            roots[key] = toAbsolute(override, env)
+            sources[key] = "override"
+            continue
+        }
+        const fromEnv = readEnv(ENV_NAMES[key], env)
+        if (fromEnv !== undefined) {
+            roots[key] = toAbsolute(fromEnv, env)
+            sources[key] = "env"
+            continue
+        }
+        roots[key] = defaults[key]
+    }
+
+    const resolved: ResolvedPaths = { ...roots, sources }
+    cached = resolved
+    return resolved
+}
+
+/** 取缓存结果，未解析时先解析一次 */
+export function getPaths(): ResolvedPaths {
+    return cached ?? initPaths()
+}
+
+/** 清空缓存，供测试使用。下次 getPaths 重新读取环境变量 */
+export function resetPaths(): void {
+    cached = null
+}
+
+/** 打印四个根目录及其来源，用于诊断 */
+export function describePaths(roots: ResolvedPaths = getPaths()): string {
+    return ROOT_KEYS.map(
+        (key) => `${ROOT_LABELS[key].padEnd(7)} ${roots[key]}  (${roots.sources[key]})`,
+    ).join("\n")
+}

package/src/plugin/access-guard.ts

@@ -0,0 +1,46 @@
+/*
+ * 插件访问守卫：插件加载/执行期间禁止直接 import 文件、进程等模块，
+ * 统一走宿主 API（api.fs / ctx.fs、api.logger 等）。
+ * 这是软隔离，无法阻止 plugin 通过 process.getBuiltinModule 等宿主逃逸。
+ */
+
+import { registerHooks } from "node:module"
+
+import { getHookOwner } from "../api/host/hooks.ts"
+
+const BLOCKED = new Set([
+    "fs",
+    "node:fs",
+    "fs/promises",
+    "node:fs/promises",
+    "child_process",
+    "node:child_process",
+    "worker_threads",
+    "node:worker_threads",
+    "vm",
+    "node:vm",
+    "module",
+    "node:module",
+    "inspector",
+    "node:inspector",
+])
+
+let installed = false
+
+export function ensureAccessGuard(): void {
+    if (installed) {
+        return
+    }
+    installed = true
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const owner = getHookOwner()
+            if (owner !== null && BLOCKED.has(specifier)) {
+                throw new Error(
+                    `插件 ${owner} 禁止直接访问 ${specifier}，请使用 api.fs / ctx.fs 等宿主 API`,
+                )
+            }
+            return nextResolve(specifier, context)
+        },
+    })
+}