@sortedyuan/plugin-runtime 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @sortedyuan/plugin-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`createRuntimePlugin(factory?, id?)` supplies `services.runtimeFactory`. Its default
+factory creates the real Core `May` runtime. Application owns each returned Runtime,
+including saving, migration and closing before plugin resources are released.
+It also accepts `{ id?, factory?, create?, dispose?, ...metadata }`; `create(context)`
+returns the Runtime factory and may use declared services and persistent state.
+Choose one of `factory` or `create` when supplying a custom source.
+
+`createContextPlugin({ id?, create?, options?, dispose? })` supplies
+`services.contextFactory`, defaulting to `InMemoryContextFactory`. `options` supplies
+the single `contextOptions` service as an object or an effective-Model callback.
+`create(context)` runs independently for each Application. `dispose(factory)` and
+`context.defer()` manage acquired resources.
+
+`createContextWrapperPlugin({ id, create, order?, dispose? })` registers
+`(factory) => ContextFactory` returned by `create(context)`. Wrappers apply in order;
+the last applied wrapper receives `create()` calls first.
+
+`createToolsPlugin({ id, create, order?, dispose? })` registers a tool source returned
+by `create(context)`: `() => Iterable<Tool>`. The contribution is automatically
+removed during plugin cleanup. Actual resource handles belong to that plugin and
+should be registered with `context.defer()`. Multiple sources compose into a
+duplicate-checked catalog captured per Run.
+Factories accept typed `config`, `configSchema`, dependencies, `requiresHooks`,
+`state`, and `version` described in
+[`PluginFactoryMetadata`](../../plugin-services/README.md). Configuration is
+validated before setup, and required registries are declared automatically.
+
+Tests use actual file handles, the Core Runtime factory and independent Context
+instances: `pnpm --filter @sortedyuan/plugin-runtime test`.

package/README.zh-CN.md

@@ -0,0 +1,26 @@
+# @sortedyuan/plugin-runtime
+
+`createRuntimePlugin(factory?, id?)` 提供 `services.runtimeFactory`。
+默认工厂创建 Core 的实际 `May` Runtime。Application 管理返回的 Runtime，
+负责保存、迁移和关闭，并在释放插件资源之前关闭 Runtime。
+也接受 `{ id?, factory?, create?, dispose?, ...metadata }`，`create(context)`
+返回 Runtime 工厂，并可以使用声明的服务和持久状态。提供自定义来源时选择 `factory` 或 `create`。
+
+`createContextPlugin({ id?, create?, options?, dispose? })` 提供 `services.contextFactory`，
+默认使用 `InMemoryContextFactory`。`options` 作为 `contextOptions` 服务，
+接受配置对象或接收当前有效 Model 的函数。每个 Application 分别调用 `create(context)`。
+通过 `dispose(factory)` 和 `context.defer()` 管理资源。
+
+`createContextWrapperPlugin({ id, create, order?, dispose? })` 注册
+`create(context)` 返回的 `(factory) => ContextFactory`。
+包装按照顺序应用，最后应用的包装首先接收 `create()` 调用。
+
+`createToolsPlugin({ id, create, order?, dispose? })` 注册工厂返回的工具来源：
+`() => Iterable<Tool>`。插件清理时自动移除条目，实际资源通过 `context.defer()` 注册清理。
+多个来源组合成工具目录，为每次 Run 保存快照，并检查重复名称。
+工厂支持 [`PluginFactoryMetadata`](../../plugin-services/README.zh-CN.md) 中带类型的
+`config`、`configSchema`、依赖、`requiresHooks`、`state` 和 `version`。
+setup 之前验证配置，并自动声明需要的注册表依赖。
+
+测试使用实际文件资源、Core Runtime 工厂和独立 Context 实例。
+执行 `pnpm --filter @sortedyuan/plugin-runtime test`。

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type RuntimeFactory } from "@sortedyuan/core";
+import { type ContextFactory } from "@sortedyuan/context";
+import { type PluginContext, type PluginDefinition, type Disposer } from "@sortedyuan/plugin";
+import { type PluginFactoryMetadata, type ContextOptionsSource, type ContextWrapper, type ContributionOptions, type ToolSource } from "@sortedyuan/plugin-services";
+export interface RuntimePluginOptions<C = unknown> extends PluginFactoryMetadata<C> {
+    readonly id?: string;
+    readonly factory?: RuntimeFactory;
+    readonly create?: (context: PluginContext<C>) => RuntimeFactory | Promise<RuntimeFactory>;
+    readonly dispose?: (factory: RuntimeFactory) => void | Promise<void>;
+}
+export declare function createRuntimePlugin<C = unknown>(factoryOrOptions?: RuntimeFactory | RuntimePluginOptions<C>, id?: string): PluginDefinition<C>;
+export interface ContextPluginOptions<C = unknown> extends PluginFactoryMetadata<C> {
+    readonly id?: string;
+    readonly create?: (context: PluginContext<C>) => ContextFactory | Promise<ContextFactory>;
+    readonly options?: ContextOptionsSource;
+    readonly dispose?: (factory: ContextFactory) => void | Promise<void>;
+}
+export declare function createContextPlugin<C = unknown>(options?: ContextPluginOptions<C>): PluginDefinition<C>;
+export interface ContextWrapperPluginOptions<C = unknown> extends Omit<ContributionOptions, "pluginOrder">, PluginFactoryMetadata<C> {
+    readonly create: (context: PluginContext<C>) => ContextWrapper | Promise<ContextWrapper>;
+    readonly dispose?: Disposer;
+}
+export declare function createContextWrapperPlugin<C = unknown>(options: ContextWrapperPluginOptions<C>): PluginDefinition<C>;
+export interface ToolsPluginOptions<C = unknown> extends Omit<ContributionOptions, "pluginOrder">, PluginFactoryMetadata<C> {
+    readonly create: (context: PluginContext<C>) => ToolSource | Promise<ToolSource>;
+    readonly dispose?: Disposer;
+}
+export declare function createToolsPlugin<C = unknown>(options: ToolsPluginOptions<C>): PluginDefinition<C>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EAA6B,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE/L,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,qBAAqB,CAAC,CAAC,CAAC;IACjF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AACD,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,gBAAgB,GAAE,cAAc,GAAG,oBAAoB,CAAC,CAAC,CAAM,EAAE,EAAE,SAAgB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CASzJ;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,qBAAqB,CAAC,CAAC,CAAC;IACjF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AACD,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,GAAE,oBAAoB,CAAC,CAAC,CAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAQ3G;AAED,MAAM,WAAW,2BAA2B,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAClI,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;CAC7B;AACD,wBAAgB,0BAA0B,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAOpH;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC;IACzH,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;CAC7B;AACD,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAOlG"}

package/dist/index.js

@@ -0,0 +1,48 @@
+import { May } from "@sortedyuan/core";
+import { InMemoryContextFactory } from "@sortedyuan/context";
+import { definePlugin } from "@sortedyuan/plugin";
+import { services, factoryMetadata } from "@sortedyuan/plugin-services";
+export function createRuntimePlugin(factoryOrOptions = {}, id = "may.runtime") {
+    const options = typeof factoryOrOptions === "function" ? { id, factory: factoryOrOptions } : factoryOrOptions;
+    if (options.create !== undefined && options.factory !== undefined)
+        throw new TypeError("Runtime plugin accepts one factory source");
+    return definePlugin({ ...factoryMetadata(options), id: options.id ?? id, provides: [services.runtimeFactory], async setup(context) {
+            const factory = options.create === undefined ? options.factory ?? ((input) => new May(input)) : await options.create(context);
+            if (options.dispose)
+                context.defer(() => options.dispose(factory));
+            if (typeof factory !== "function")
+                throw new TypeError("Runtime plugin must create a RuntimeFactory");
+            context.provide(services.runtimeFactory, factory);
+        } });
+}
+export function createContextPlugin(options = {}) {
+    return definePlugin({ ...factoryMetadata(options), id: options.id ?? "may.context", provides: [services.contextFactory, ...(options.options === undefined ? [] : [services.contextOptions])], async setup(context) {
+            const factory = options.create === undefined ? new InMemoryContextFactory() : await options.create(context);
+            if (options.dispose)
+                context.defer(() => options.dispose(factory));
+            if (typeof factory?.create !== "function")
+                throw new TypeError("Context plugin must create a ContextFactory");
+            context.provide(services.contextFactory, factory);
+            if (options.options !== undefined)
+                context.provide(services.contextOptions, options.options);
+        } });
+}
+export function createContextWrapperPlugin(options) {
+    return definePlugin({ ...factoryMetadata(options, [{ service: services.contextWrappers }]), id: options.id, async setup(context) {
+            if (options.dispose)
+                context.defer(options.dispose);
+            context.defer(context.get(services.contextWrappers).add(await options.create(context), {
+                id: context.pluginId, pluginOrder: context.pluginOrder, ...(options.order === undefined ? {} : { order: options.order }),
+            }));
+        } });
+}
+export function createToolsPlugin(options) {
+    return definePlugin({ ...factoryMetadata(options, [{ service: services.toolSources }]), id: options.id, async setup(context) {
+            if (options.dispose)
+                context.defer(options.dispose);
+            context.defer(context.get(services.toolSources).add(await options.create(context), {
+                id: context.pluginId, pluginOrder: context.pluginOrder, ...(options.order === undefined ? {} : { order: options.order }),
+            }));
+        } });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@sortedyuan/plugin-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.3",
+  "description": "Runtime, context and tool plugin factories.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@sortedyuan/core": "0.2.0",
+    "@sortedyuan/context": "0.2.0",
+    "@sortedyuan/plugin": "0.2.0",
+    "@sortedyuan/plugin-services": "0.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "test:coverage": "pnpm run build && node --test --experimental-test-coverage test/*.test.mjs"
+  }
 }