@zhin.js/schema 1.1.5 → 1.1.6

package/README.md

@@ -207,8 +207,8 @@ plugins:
 | `.default(value)` | 设置默认值 |
 | `.option(label, value)` | 添加可选项 |
 | `.multiple()` | 允许多选 |
-| `.min(value)` | 设置最小值 |
-| `.max(value)` | 设置最大值 |
+| `.min(value)` | 设置最小值（数字下限 / 字符串最小长度 / 列表最少项）；写入导出的 JSON Schema，由 Runtime 配置校验执行，`schema(value)` 与 `safeParse` 只做结构校验 |
+| `.max(value)` | 设置最大值，规则同 `.min` |
 | `.step(value)` | 设置步长 |
 | `.component(name)` | 指定渲染组件 |
 | `.toJSON()` | 业务 Schema 的内部序列化 |

package/lib/json-schema.d.ts

@@ -12,6 +12,15 @@ export interface ConfigFieldMetadata {
     readonly component?: string;
     readonly options?: readonly Schema.Option[];
     readonly effect?: 'reload';
+    /** Property-level narrowing of the Plugin's feature levels (ADR 0050 §2). */
+    readonly levels?: readonly ('global' | 'adapter' | 'endpoint' | 'conversation')[];
+}
+/** Root `x-zhin-config` of a Plugin schema: layered levels (ADR 0050 / 0055). */
+export interface ConfigFeatureLevels {
+    readonly levels: readonly ('global' | 'adapter' | 'endpoint' | 'conversation')[];
+    readonly conversationFields?: readonly string[];
+    readonly selfServiceFields?: readonly string[];
+    readonly chatAdminFields?: readonly string[];
 }
 export type ConfigJsonSchema = Readonly<Record<string, unknown>>;
 /** Export serializable configuration declarations; non-JSON business types are explicit errors. */

package/lib/json-schema.js

@@ -100,6 +100,8 @@ export function toJsonSchema(schema) {
         ...(meta.component !== undefined ? { component: meta.component } : {}),
         ...(meta.options !== undefined ? { options: structuredClone(meta.options) } : {}),
         ...(meta.effect !== undefined ? { effect: meta.effect } : {}),
+        ...(meta.feature !== undefined ? structuredClone(meta.feature) : {}),
+        ...(meta.fieldLevels !== undefined ? { levels: [...meta.fieldLevels] } : {}),
     };
     if (Object.keys(annotations).length)
         result['x-zhin-config'] = annotations;

package/lib/schema.d.ts

@@ -1,5 +1,5 @@
 import { safeParseSchema, type SchemaSafeParseResult } from './validate.js';
-import { type ConfigFieldMetadata, type ConfigFieldI18n } from './json-schema.js';
+import { type ConfigFeatureLevels, type ConfigFieldMetadata, type ConfigFieldI18n } from './json-schema.js';
 export { SchemaValidationError, type SchemaSafeParseResult, type SchemaValidationIssue } from './validate.js';
 export { safeParseSchema };
 declare const configPresent: unique symbol;
@@ -31,13 +31,31 @@ export declare class Schema<S = any, T = S> {
     secret(): this;
     /** Declare the effect shown in configuration forms. */
     effect(effect: ConfigFieldMetadata['effect']): this;
+    /**
+     * Plugin root only: layered feature levels (ADR 0050 / 0055) and the fields editable at the
+     * conversation level, in chat by group admins, and in chat above the conversation level.
+     */
+    featureLevels(levels: ConfigFeatureLevels['levels'], fields?: Omit<ConfigFeatureLevels, 'levels'>): this;
+    /**
+     * Plugin property only: narrow the feature levels that may override this field (ADR 0050 §2),
+     * e.g. `.fieldLevels(['global'])` for secrets and process-wide resources. It can never widen
+     * the root `featureLevels` declaration; the Runtime rejects a wider list at startup.
+     */
+    fieldLevels(levels: ConfigFeatureLevels['levels']): this;
     /** Export the standard JSON Schema consumed by Runtime and Console. */
     toJsonSchema(): Readonly<Record<string, unknown>>;
     /** 设置选项列表 */
     option(list: (T | Schema.Option<T>)[]): this;
     /** 设置是否允许多选 */
     multiple(): this;
-    /** 设置最小值 */
+    /**
+     * 设置最小值。
+     * `min` / `max` / `step` are range constraints of the exported JSON Schema
+     * (minimum/minLength/minItems, maximum/…, multipleOf) and are enforced where that
+     * schema is compiled (Runtime config validation). The callable schema and
+     * `safeParse` are structural only; `toJsonSchema` relies on that when it matches
+     * union branches (see assertPublicDefault).
+     */
     min(value: number): this;
     /** 设置最大值 */
     max(value: number): this;
@@ -125,6 +143,8 @@ export declare namespace Schema {
         step?: number;
         secret?: boolean;
         effect?: ConfigFieldMetadata['effect'];
+        feature?: ConfigFeatureLevels;
+        fieldLevels?: ConfigFeatureLevels['levels'];
     }
     interface Options {
         object?: Record<string, Schema>;

package/lib/schema.js

@@ -102,6 +102,27 @@ export class Schema {
         this.meta.effect = effect;
         return this;
     }
+    /**
+     * Plugin root only: layered feature levels (ADR 0050 / 0055) and the fields editable at the
+     * conversation level, in chat by group admins, and in chat above the conversation level.
+     */
+    featureLevels(levels, fields = {}) {
+        if (this.meta.type !== 'object')
+            throw new TypeError('featureLevels only supports the plugin root object');
+        this.meta.feature = structuredClone({ levels, ...fields });
+        return this;
+    }
+    /**
+     * Plugin property only: narrow the feature levels that may override this field (ADR 0050 §2),
+     * e.g. `.fieldLevels(['global'])` for secrets and process-wide resources. It can never widen
+     * the root `featureLevels` declaration; the Runtime rejects a wider list at startup.
+     */
+    fieldLevels(levels) {
+        if (!levels.length || !levels.includes('global'))
+            throw new TypeError('fieldLevels must include global');
+        this.meta.fieldLevels = [...levels];
+        return this;
+    }
     /** Export the standard JSON Schema consumed by Runtime and Console. */
     toJsonSchema() {
         return toJsonSchema(this);
@@ -118,7 +139,14 @@ export class Schema {
         this.meta.multiple = true;
         return this;
     }
-    /** 设置最小值 */
+    /**
+     * 设置最小值。
+     * `min` / `max` / `step` are range constraints of the exported JSON Schema
+     * (minimum/minLength/minItems, maximum/…, multipleOf) and are enforced where that
+     * schema is compiled (Runtime config validation). The callable schema and
+     * `safeParse` are structural only; `toJsonSchema` relies on that when it matches
+     * union branches (see assertPublicDefault).
+     */
     min(value) {
         this.meta.min = value;
         return this;
@@ -366,8 +394,12 @@ Schema.extend('const', function (key, value) {
     return value;
 });
 Schema.extend('tuple', function (key, value) {
-    value = Schema.checkDefault(this, key, value, []);
-    if (value.length > 0 && value.length !== this.options.list.length)
+    // No `[]` fallback: an empty array is not a valid tuple (JSON Schema exports
+    // minItems = maxItems = length, and safeParse rejects it), so absent stays absent.
+    value = Schema.checkDefault(this, key, value);
+    if (value === undefined)
+        return value;
+    if (value.length !== this.options.list.length)
         throw new TypeError(`${key} tuple length mismatch`);
     return value.map((item, index) => this.options.list[index](item, `${key}[${index}]`));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/schema",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Configuration validation and schema system for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,10 @@
   "files": [
     "lib"
   ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3"