yeow-api 0.2.113 → 0.2.115

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.2.113",
+    "version": "0.2.115",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/command.ts

@@ -1,11 +1,16 @@
 import { call } from './task.js';
 import type { TaskOptions } from './task.js';
+import { Player } from './player.js';
+import type { Permission } from './permission.js';
+import type { PermissionOptions } from './permission.js';
+import { permissionPayload } from './permission.js';
 
-export interface CommandSender {
-  readonly name: string;
-  readonly uuid: string;
-  readonly isPlayer: boolean;
-  sendMessage(msg: string): void;
+/** 命令发送者：玩家为真正的 `Player` 对象（异步 `sendMessage` 等全部方法）；控制台为字符串 `'CONSOLE'`。 */
+export type CommandSender = Player | 'CONSOLE';
+
+/** 判断发送者是否为玩家（非 'CONSOLE' 即玩家）。 */
+export function isPlayer(sender: CommandSender): sender is Player {
+  return sender !== 'CONSOLE';
 }
 
 export interface CommandPayload {
@@ -23,7 +28,12 @@ export interface ManualCompleter {
 export interface CommandOptions {
   description?: string;
   usage?: string;
-  permission?: string;
+  /**
+   * 权限节点：字符串（兼容）或权限节点对象 `{ node, default }`（或 `registerPermission` 返回值）。
+   * 节点注册进 Bukkit 权限系统（权限插件/ permissions.yml 可管理）；**执行时检查**——
+   * `permissionCheck` 事件结果优先，无处理时回退 Bukkit `hasPermission`。未声明则所有人可执行。
+   */
+  permission?: string | Permission | PermissionOptions;
   aliases?: string[];
   executor: (payload: CommandPayload) => void;
   completer?: CompleterFn | ManualCompleter;
@@ -34,21 +44,17 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
   const completer = options.completer;
   const pluginName = __plugin?.name || 'unknown';
 
-  function decorateSender(sender: CommandSender): CommandSender {
-    if (sender?.uuid && sender.isPlayer) {
-      (sender as any).sendMessage = (msg: string) => {
-        call('player.sendMessage', { uuid: sender.uuid, message: msg }, taskOptions);
-      };
-    } else {
-      (sender as any).sendMessage = (msg: string) => {
-        $send('log', { level: 'INFO', message: msg });
-      };
+  /** 原始 sender（{name, uuid, isPlayer}）→ 真正的 Player 或 'CONSOLE'。 */
+  function adaptSender(raw: any): CommandSender {
+    if (raw?.isPlayer) {
+      const p = Player.getSync(raw.uuid);
+      if (p) return p;
     }
-    return sender;
+    return 'CONSOLE';
   }
 
   const cbId = _registerCallback((payload: CommandPayload) => {
-    (payload as any).sender = decorateSender(payload.sender);
+    (payload as any).sender = adaptSender(payload.sender);
     executor(payload);
   }, { persistent: true });
 
@@ -65,7 +71,7 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
 
     compCbId = _registerCallback((data: any) => {
       try {
-        const sender = decorateSender(data.sender);
+        const sender = adaptSender(data.sender);
         if (manualRelease) {
           const complete = (result: string[]) => {
             $send('task', {
@@ -108,7 +114,7 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
     completerCbId: compCbId,
     description: options.description,
     usage: options.usage,
-    permission: options.permission,
+    permission: options.permission ? permissionPayload(options.permission) : undefined,
     aliases: options.aliases,
   }, taskOptions);
 }

package/src/core.ts

@@ -27,6 +27,7 @@ export type {
     BlockBreakEvent, BlockPlaceEvent, BlockFadeEvent, BlockGrowEvent, BlockSpreadEvent, BlockExplodeEvent,
     InventoryOpenEvent, InventoryCloseEvent, InventoryClickEvent,
     ServerPingEvent, ServerCommandEvent,
+    PermissionCheckEvent,
     PlayerResourcePackStatusEvent,
 } from './event.js';
 export { onInit, onLoad, onUnload } from './lifecycle.js';
@@ -92,3 +93,9 @@ export { registerService, registerNativeService, request as serviceRequest, subs
 export type { ServiceResult, NativeServiceResult } from './service.js';
 export { log, Logger } from './log.js';
 export type { Message } from './message.js';
+export { getEnv } from './env.js';
+export type { EnvInfo } from './env.js';
+export { registerPermission } from './permission.js';
+export type { Permission, PermissionOptions, PermissionDefault } from './permission.js';
+export { createWorker, Worker, onMessage, postMessage } from './worker.js';
+export type { WorkerOptions } from './worker.js';

package/src/env.ts

@@ -0,0 +1,20 @@
+/** env 通道返回的运行时环境信息（同步）。 */
+export interface EnvInfo {
+  /** CPU 逻辑核心数。 */
+  cpus: number;
+  /** JVM 总内存（字节）。 */
+  memory: number;
+  /** 系统架构（如 `windows-x64` / `linux-x64` / `linux-arm64`）。 */
+  arch: string;
+  /** Minecraft 版本（如 `1.21.4`）。 */
+  minecraftVersion: string;
+  /** 运行时信息。 */
+  yeow: { platform: string; version: string };
+  /** epoch 微秒时间戳。 */
+  now: number;
+}
+
+/** 获取运行时环境信息（同步；含微秒时间戳）。 */
+export function getEnv(): EnvInfo {
+  return $send('env', {}) as EnvInfo;
+}

package/src/event.ts

@@ -254,6 +254,27 @@ export interface ServerCommandEvent {
   sender: string;
   cancelled?: boolean;
 }
+
+/**
+ * Yeow 生态权限检查（仅 `player.hasPermission` 任务与 Yeow 插件注册命令的执行检查触发；
+ * 其他 Java 插件的 hasPermission / 命令不会触发）。
+ *
+ * handler 返回 `{ allowed: <boolean> }` 决定结果；**不返回视为未处理**（回退 Bukkit hasPermission）。
+ * 多个 handler 都返回且结果冲突时，以**最后一个返回的为准**（不保证执行顺序）。
+ *
+ * ⚠ 普通插件不建议监听（每次权限检查都触发，影响性能）——专为 Yeow 生态权限管理插件设计。
+ * ⚠ handler 中调用 `hasPermission` 会再次触发本检查——**可能导致无限循环**，请避免。
+ */
+export interface PermissionCheckEvent {
+  /** 检查对象：玩家 UUID 或 "CONSOLE"。 */
+  target: string;
+  /** 权限节点（如 "myplugin.home"）。 */
+  node: string;
+  /** 权限对象（含节点默认值，`registerPermission` 或命令声明的权限）。 */
+  permission: { node: string; default?: string };
+  /** handler 返回 `{ allowed }` 决定结果。 */
+  allowed?: boolean;
+}
 export interface InventoryClickEvent {
   player: Player;
   slot: number;
@@ -316,6 +337,7 @@ type EventMap = {
   inventoryClose: InventoryCloseEvent;
   serverPing: ServerPingEvent;
   serverCommand: ServerCommandEvent;
+  permissionCheck: PermissionCheckEvent;
   playerTeleport: PlayerTeleportEvent;
   playerItemConsume: PlayerItemConsumeEvent;
   inventoryClick: InventoryClickEvent;

package/src/global.d.ts

@@ -11,6 +11,7 @@ declare global {
   function _unregisterCallback(id: string): void;
   function _getCurrentCbStack(): { stack: string; outer: unknown } | null;
   function _attachCbStack(err: unknown): void;
+  function reportError(e: unknown): void;
 
   // ── init.js 注入的标准环境（lib 为 ESNext，不含 DOM——自行声明）──
   interface YeowConsole {

package/src/permission.ts

@@ -0,0 +1,46 @@
+import { call } from './task.js';
+import type { TaskOptions } from './task.js';
+
+/** 权限节点默认值：'all' = 所有人默认拥有；'op' = 仅 op（默认）；'none' = 需授权。 */
+export type PermissionDefault = 'all' | 'op' | 'none';
+
+export interface PermissionOptions {
+  /** 权限节点（如 `myplugin.home`）。 */
+  node: string;
+  /** 默认值（默认 'op'）。 */
+  default?: PermissionDefault;
+}
+
+/** 权限节点对象（注册后返回）。 */
+export interface Permission {
+  node: string;
+  default: PermissionDefault;
+}
+
+let _registered: Record<string, Permission> = {};
+
+/**
+ * 注册权限节点（幂等）：节点注册进 Bukkit 权限系统——Paper 平台可通过
+ * `permissions.yml` 静态声明或 LuckPerms 等权限管理插件管理。
+ *
+ * 粒度较粗（只声明默认值）；Yeow 生态内可由权限管理插件通过 `permissionCheck`
+ * 事件实现任意逻辑的权限管理。
+ */
+export function registerPermission(options: PermissionOptions, taskOptions?: TaskOptions): Permission {
+  const node = options?.node;
+  if (!node || typeof node !== 'string' || node.trim() === '') {
+    throw new Error('registerPermission: node is required');
+  }
+  const def: PermissionDefault = options.default || 'op';
+  if (!_registered[node]) {
+    call('permission.register', { node, default: def }, taskOptions);
+    _registered[node] = { node, default: def };
+  }
+  return _registered[node];
+}
+
+/** 权限节点对象 → 请求载荷（{ node, default }）；字符串包装为对象（default 默认 'op'）——Java 侧不做兼容。 */
+export function permissionPayload(perm: string | Permission | PermissionOptions): { node: string; default: PermissionDefault } {
+  if (typeof perm === 'string') return { node: perm, default: 'op' };
+  return { node: perm.node, default: perm.default || 'op' };
+}

package/src/player.ts

@@ -3,6 +3,7 @@ import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
 import type { ItemStack } from './item.js';
 import type { Message } from './message.js';
+import type { Permission } from './permission.js';
 
 interface PlayerData {
   uuid: string;
@@ -135,11 +136,19 @@ export class Player {
   }
   giveExp(amount: number, options?: TaskOptions): Promise<void> { return post('player.giveExp', { uuid: this.uuid, amount }, options); }
   giveExpSync(amount: number, options?: TaskOptions): void { call('player.giveExp', { uuid: this.uuid, amount }, options); }
-  hasPermission(node: string, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('player.hasPermission', { uuid: this.uuid, permission: node }, options);
+  /** 检查权限（经 Yeow 权限检查：`permissionCheck` 事件优先，无处理时回退 Bukkit）。node 可为权限节点对象。 */
+  hasPermission(node: string | Permission, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? node : { node: node.node } }, options);
   }
-  hasPermissionSync(node: string, options?: TaskOptions): boolean {
-    return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: node }, options);
+  hasPermissionSync(node: string | Permission, options?: TaskOptions): boolean {
+    return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? node : { node: node.node } }, options);
+  }
+  /** 以玩家身份执行命令（**不含 `/` 前缀**，如 `say hi`；前缀会自动剥离；与服务器 `dispatchCommand`（控制台）相对）。 */
+  performCommand(cmd: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.performCommand', { uuid: this.uuid, command: cmd.replace(/^\//, '') }, options);
+  }
+  performCommandSync(cmd: string, options?: TaskOptions): boolean {
+    return call<boolean>('player.performCommand', { uuid: this.uuid, command: cmd.replace(/^\//, '') }, options);
   }
   teleport(loc: Location, options?: TaskOptions): Promise<void> { return post('player.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
   teleportSync(loc: Location, options?: TaskOptions): void { call('player.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }

package/src/worker.ts

@@ -0,0 +1,150 @@
+export interface WorkerOptions {
+  /** Worker 名（必填；不允许 'main'；同一主插件内不重复，全局可重复）。 */
+  name: string;
+  /** 资源路径（通过 `getAssetsPath` 获取）；与 `code` 互斥（不可同时传递）。 */
+  entry?: string;
+  /** 代码字符串；与 `entry` 互斥。 */
+  code?: string;
+}
+
+let _seq = 0;
+/** 本主插件已创建的 worker 名（同主插件内唯一校验；unload 后允许重建）。 */
+const _created: Record<string, boolean> = {};
+/** 主插件侧：每个 worker 的 onMessage 回调 id。 */
+const _msgCbs: Record<string, string> = {};
+
+function _sendWorker(payload: Record<string, unknown>): unknown {
+  const r = $send('worker', payload);
+  if (r == null) return undefined;
+  if ((r as any)?.err) throw new Error((r as any).err);
+  return r;
+}
+
+/** 内部：异步调用 worker 通道（cb 回调）。 */
+function _sendWorkerAsync(t: string, p: Record<string, unknown>): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const cbId = _registerCallback((result: unknown) => {
+      if ((result as any)?.err) reject(new Error((result as any).err));
+      else resolve();
+    });
+    _sendWorker({ t, p: { ...p, cb: cbId } });
+  });
+}
+
+/**
+ * Worker —— 虚拟插件（独立 QuickJS 上下文 + 线程）。
+ *
+ * - 事件/命令/服务以独立实体注册；调度器任务独立统计
+ * - 共享主插件的**数据目录**与**权限**
+ * - 不能创建新的 Worker（嵌套被拒绝）
+ * - **创建后无法销毁，只能卸载**（卸载物理销毁 JS 上下文，句柄保留——可重新 load）
+ * - 主插件卸载时连带卸载；/yeow 管理命令不覆盖 Worker；profiler 会统计（标记 created by 主插件）
+ * - Worker 的 JS 错误与主插件同样回传（dev 模式经 source-map 定位）
+ */
+export class Worker {
+  private readonly name: string;
+  private readonly entry?: string;
+  private readonly code?: string;
+  private readonly key: string;
+  private _loaded = false;
+  private _onMessage: ((msg: any) => void) | null = null;
+  /** 内部 workerId（主插件 JS 侧分配；跨主插件可重复）。 */
+  readonly id: string;
+
+  constructor(name: string, entry: string | undefined, code: string | undefined) {
+    this.name = name;
+    this.entry = entry;
+    this.code = code;
+    this.id = 'worker_' + (++_seq);
+    this.key = (__plugin?.name || 'unknown') + ':' + name;
+    // 主插件侧 onMessage 回调（worker → main 时 Java 投递到这里）
+    _msgCbs[this.id] = _registerCallback((msg: unknown) => {
+      const cb = this._onMessage;
+      if (cb) { try { cb(msg); } catch (e) { console.error('[worker] onMessage error', e); } }
+    }, { persistent: true });
+  }
+
+  /** 注册接收 Worker 发来的消息。 */
+  onMessage(cb: (msg: any) => void): void {
+    this._onMessage = cb;
+  }
+
+  /** 启动 Worker：执行 init.js → worker-inject.js → Worker 代码 → INIT → LOAD（已加载为 no-op）。 */
+  load(): Promise<void> {
+    if (this._loaded) return Promise.resolve();
+    this._loaded = true;
+    return _sendWorkerAsync('load', { name: this.name });
+  }
+
+  /** 卸载 Worker（物理销毁 JS 上下文并清理其事件/命令/服务/任务；句柄保留，可重新 load）。 */
+  unload(): Promise<void> {
+    this._loaded = false;
+    return _sendWorkerAsync('unload', { name: this.name });
+  }
+
+  /** 向 Worker 发送消息（其 onMessage 回调接收；未 load 时抛错）。 */
+  postMessage(msg: Record<string, unknown>): Promise<void> {
+    return _sendWorkerAsync('post', { name: this.name, msg });
+  }
+
+  /** 重载 Worker 代码（需已 load；旧上下文销毁、新代码重新加载）。 */
+  reload(): Promise<void> {
+    const p: Record<string, unknown> = { name: this.name };
+    if (this.entry) p.entry = this.entry;
+    else p.code = this.code;
+    return _sendWorkerAsync('reload', p);
+  }
+}
+
+/**
+ * 创建 Worker（虚拟插件）：**仅注册到注册表并返回句柄**——`worker.load()` 才真正启动
+ * （执行 init.js → worker-inject.js → Worker 代码 → INIT → LOAD）。
+ *
+ * `entry`（资源路径，经 getAssetsPath）与 `code` 二选一，同时传递抛错；
+ * `name` 必填、非 'main'、同主插件内不重复。
+ */
+export function createWorker(options: WorkerOptions): Worker {
+  const name = options?.name;
+  if (!name || typeof name !== 'string' || name.trim() === '') {
+    throw new Error('createWorker: name is required');
+  }
+  if (name === 'main') {
+    throw new Error('createWorker: name must not be "main"');
+  }
+  if (options.entry && options.code) {
+    throw new Error('createWorker: entry and code cannot be passed together');
+  }
+  if (!options.entry && !options.code) {
+    throw new Error('createWorker: either entry or code is required');
+  }
+  const key = (__plugin?.name || 'unknown') + ':' + name;
+  if (_created[key]) {
+    throw new Error('createWorker: duplicate worker name "' + name + '" in plugin ' + (__plugin?.name || 'unknown'));
+  }
+  _created[key] = true;
+  const w = new Worker(name, options.entry, options.code);
+  // 注册到运行时注册表（同步；重复/非法名抛错）
+  const p: Record<string, unknown> = { name, msgCb: _msgCbs[w.id] };
+  if (options.entry) p.entry = options.entry;
+  else p.code = options.code;
+  _sendWorker({ t: 'create', p });
+  return w;
+}
+
+// ── Worker 侧 API（仅 Worker 环境可用）──────────────────────────────
+
+const _isWorker = typeof (globalThis as any).__workerId !== 'undefined';
+
+/** Worker 侧：注册消息接收回调（主插件 `worker.postMessage` 触发）。主插件环境调用抛错。 */
+export function onMessage(cb: (msg: any) => void): void {
+  if (!_isWorker) throw new Error('onMessage is only available inside a Worker');
+  (globalThis as any)._workerOnMessage = (msg: any) => {
+    try { cb(msg); } catch (e) { reportError(e); }
+  };
+}
+
+/** Worker 侧：向主插件发送消息（主插件侧 `worker.onMessage` 回调接收）。主插件环境调用抛错。 */
+export function postMessage(msg: Record<string, unknown>): void {
+  if (!_isWorker) throw new Error('postMessage is only available inside a Worker');
+  _sendWorker({ t: 'postToMain', p: { msg } });
+}