@qilin-agent/client-schema-form 0.0.0-stage → 3.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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.i18n.yaml

@@ -0,0 +1,28 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/schema-form/README.md
+/:
+  en: 29df4c8e1bc00a92
+  zh: 1f10d0b3ef6edddd
+/qilin-agent-client-schema-form:
+  en: b9f0043a06e0f834
+  zh: 503ec8030ec56db2
+/qilin-agent-client-schema-form/summary:
+  en: 4f9409a1d4c655ba
+  zh: 2ae30bee38ce2869
+/qilin-agent-client-schema-form/table-of-contents:
+  en: b4683d2a53256fda
+  zh: 4e65ff63dc8c48fe
+/qilin-agent-client-schema-form/model-experience:
+  en: bdb6bdc139b7f5a7
+  zh: feca992d9b340e0b
+/qilin-agent-client-schema-form/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: de54f3467ef3b9be
+/qilin-agent-client-schema-form/known-limitations-and-deferred-work:
+  en: 6ab3a1e79b9555a9
+  zh: 14695aac0fc46105
+/qilin-agent-client-schema-form/known-limitations-and-deferred-work/dev-note:
+  en: 08801a2906bf9717
+  zh: 363e3669de77dc34

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+---
+description: "Schema and draft model layer behind configuration editors: rehydrate a serialized schemastery envelope, validate drafts, and edit them immutably by path."
+kind: "package-library"
+---
+# @qilin-agent/client-schema-form
 
-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.
+English | [中文](README.zh.md)
+
+## Summary
+
+Schema introspection and immutable draft editing for the configuration editors of the web client. A Host row publishes its declared schemastery `Config` as the serialized `schema.toJSON()` envelope, and `rehydrateSchema` turns that envelope back into a live node tree, so the same schema that validates a row on the Host validates a draft in the browser. `setPath`, `deletePath`, `nodeAtPath`, and `validateDraft` apply and reject a draft by path; the package owns no React and no rendering.
+
+Consumers: `@qilin-agent/client-ui-settings` serves these helpers as `ctx.settingsSchema`, and `@qilin-agent/client-ui-plugin-manager` builds a row's configuration form over them.
+
+## Table of Contents
+
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package backs browser configuration editors; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Rehydration executes the served envelope** — `rehydrateSchema` reconstructs a live schemastery validator, and schemastery revives serialized callbacks through `new Function`, so the schema envelope is executable content rather than inert data. This is safe only for an envelope from the same trusted host that serves the page; the protocol provides no inert cross-trust representation.
+- **Validation is draft-level, not per-field** — `validateDraft` reports schemastery's first failure message, including its `$.path`; it does not map errors onto individual controls.
+- **No generic renderer** — consumers build their own controls over these helpers. Every configuration surface in this repository decides its own layout; the [Web configuration plane Agent Note](../../../.agents/notes/archived/architecture/2026-07-30-web-config-plane.md) records why the schema dump that a fully generic renderer produced was rejected.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+The package is built with the `staticLinked` preset and named in `INLINE_SAFE` in [`tsdown.client.ts`](../tsdown.client.ts): its exports are pure folds with no runtime identity to share, so a dynamic browser bundle inlines its own copy instead of requesting a module-table row.
+
+</details>

package/README.zh.md

@@ -0,0 +1,48 @@
+---
+description: "配置编辑器背后的 schema 与草稿模型层：还原序列化的 schemastery 封装、校验草稿，并按路径以不可变方式编辑。"
+kind: "package-library"
+---
+# @qilin-agent/client-schema-form
+
+[English](README.md) | 中文
+
+## 概述
+
+Web 客户端各配置编辑器共用的 schema 内省与不可变草稿编辑。Host 行把自身声明的 schemastery `Config` 以序列化的 `schema.toJSON()` 封装发布出来，`rehydrateSchema` 把该封装还原成活的节点树，因此宿主机上校验某一行的那份 schema，就是浏览器里校验草稿的那份 schema。`setPath`、`deletePath`、`nodeAtPath` 与 `validateDraft` 按路径施加或拒绝草稿；该包不含任何 React，也不做任何渲染。
+
+使用方：`@qilin-agent/client-ui-settings` 以 `ctx.settingsSchema` 提供这批辅助函数，`@qilin-agent/client-ui-plugin-manager` 在其之上构建行的配置表单。
+
+## 目录
+
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。该包支撑的是浏览器配置编辑器；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **重建 schema 会执行所收到的封装**——`rehydrateSchema` 会重建一个活的 schemastery 校验器，而 schemastery 通过 `new Function` 复活序列化过的回调函数，因此 schema 信封是可执行内容，而不是不可执行数据。只有该封装来自提供该页面的同一受信任宿主时才安全；该协议没有跨信任边界使用的不可执行表示。
+- **校验是草稿级的，而非逐字段的**——`validateDraft` 报告 schemastery 的第一条失败消息及其 `$.path`；它不会把错误映射到各个控件。
+- **没有通用渲染器**——消费方在这些辅助函数之上构建自己的控件。本仓库的每个配置界面都自行决定布局；[Web 配置面 Agent Note](../../../.agents/notes/archived/architecture/2026-07-30-web-config-plane.md) 记录了完全通用渲染器产出的 schema 转储为何被否决。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+该包以 `staticLinked` 预设构建，并在 [`tsdown.client.ts`](../tsdown.client.ts) 的 `INLINE_SAFE` 中登记：它的导出是无运行期身份可共享的纯函数折叠，因此动态浏览器包内联自己的副本，而不申请模块表行。
+
+</details>

package/lib/index.js

@@ -0,0 +1,141 @@
+import Schema from "@qilin-agent/schemastery";
+//#region lib/types/model.js
+/**
+* Schema introspection and draft-editing helpers behind settings editors.
+* The serialized schemastery envelope (`schema.toJSON()`) rehydrates into a
+* live validator whose node relations (`dict`/`inner`) editors probe for
+* field presence and roles; drafts are edited immutably by path.
+* @module @qilin-agent/client-schema-form/model
+*/
+/**
+* Rehydrate a serialized schema envelope into a live validator/node tree.
+* @param serialized - `schema.toJSON()` output received over the wire.
+* @returns the root schema node.
+*/
+function rehydrateSchema(serialized) {
+	return new Schema(serialized);
+}
+/**
+* Validate a draft against a rehydrated schema.
+* @param schema - rehydrated root node.
+* @param draft - candidate value.
+* @returns the validation failure message, or `undefined` when the draft passes.
+*/
+function validateDraft(schema, draft) {
+	try {
+		schema(draft);
+		return;
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+}
+/**
+* Resolve the schema node at a settings path (the configurable-provider
+* directory's `settingsPath` vocabulary): object properties by name, dict
+* entries through `inner`. An unresolvable segment returns `undefined` so
+* the caller falls back instead of rendering a wrong subtree.
+* @param root - rehydrated section root node.
+* @param path - key path from the section root.
+* @returns the node describing that position, or `undefined`.
+*/
+function nodeAtPath(root, path) {
+	let node = root;
+	for (const key of path) {
+		if (node === void 0) return void 0;
+		if (node.type === "object") node = node.dict?.[key];
+		else if (node.type === "dict" || node.type === "array") node = node.inner;
+		else return void 0;
+	}
+	return node;
+}
+/**
+* Read a nested value by path.
+* @param value - root value (draft or fallback layer).
+* @param path - key path from the root; array indexes as strings.
+* @returns the value at the path, or `undefined` along a missing branch.
+*/
+function getPath(value, path) {
+	let current = value;
+	for (const key of path) {
+		if (Array.isArray(current)) {
+			current = current[Number(key)];
+			continue;
+		}
+		if (typeof current !== "object" || current === null) return void 0;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* Whether a draft explicitly carries the path (its presence marks a user
+* override, independent of the value stored there).
+* @param value - root value (draft or fallback layer).
+* @param path - key path from the root; array indexes as strings.
+* @returns whether the path's final key exists on its parent.
+*/
+function hasPath(value, path) {
+	if (path.length === 0) return value !== void 0;
+	const parent = getPath(value, path.slice(0, -1));
+	const key = path[path.length - 1];
+	if (Array.isArray(parent)) return Number(key) < parent.length;
+	if (typeof parent !== "object" || parent === null) return false;
+	return key in parent;
+}
+function cloneContainer(container, key) {
+	if (Array.isArray(container)) return [...container];
+	if (typeof container === "object" && container !== null) return { ...container };
+	return /^\d+$/.test(key) ? [] : {};
+}
+/** Clone the container spine down to the leaf's parent, materializing missing intermediates. */
+function cloneSpine(root, path) {
+	const result = { ...root };
+	let target = result;
+	for (let i = 0; i < path.length - 1; i++) {
+		const key = path[i];
+		const child = cloneContainer(Array.isArray(target) ? target[Number(key)] : target[key], path[i + 1]);
+		if (Array.isArray(target)) target[Number(key)] = child;
+		else target[key] = child;
+		target = child;
+	}
+	return {
+		result,
+		parent: target,
+		leaf: path[path.length - 1]
+	};
+}
+/**
+* Immutably set a nested value, materializing missing intermediate containers.
+* @param root - draft root (never mutated).
+* @param path - non-empty key path.
+* @param value - value to store at the path.
+* @returns the new draft root.
+* @throws when `path` is empty.
+*/
+function setPath(root, path, value) {
+	if (path.length === 0) throw new Error("schema-form: setPath needs a non-empty path");
+	const { result, parent, leaf } = cloneSpine(root, path);
+	if (Array.isArray(parent)) parent[Number(leaf)] = value;
+	else parent[leaf] = value;
+	return result;
+}
+/**
+* Immutably remove a nested key (the per-field reset: the resolved value
+* falls back to the composition base and schema defaults). Removing along a
+* missing branch returns the root unchanged.
+* @param root - draft root (never mutated).
+* @param path - non-empty key path.
+* @returns the new draft root.
+* @throws when `path` is empty.
+*/
+function deletePath(root, path) {
+	if (path.length === 0) throw new Error("schema-form: deletePath needs a non-empty path");
+	if (!hasPath(root, path)) return root;
+	const { result, parent, leaf } = cloneSpine(root, path);
+	if (Array.isArray(parent)) parent.splice(Number(leaf), 1);
+	else Reflect.deleteProperty(parent, leaf);
+	return result;
+}
+//#endregion
+export { deletePath, getPath, hasPath, nodeAtPath, rehydrateSchema, setPath, validateDraft };
+
+//# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Schema/draft model layer for configuration editors: rehydrate the wire's
+ * serialized schemastery envelope, resolve nodes by settings path, validate
+ * drafts, and edit them immutably by path. Editors render their own controls
+ * on top of these helpers.
+ * @module @qilin-agent/client-schema-form
+ */
+export { deletePath, getPath, hasPath, nodeAtPath, rehydrateSchema, setPath, validateDraft, } from './model.ts';
+export type { SchemaNode } from './model.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/model.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Schema introspection and draft-editing helpers behind settings editors.
+ * The serialized schemastery envelope (`schema.toJSON()`) rehydrates into a
+ * live validator whose node relations (`dict`/`inner`) editors probe for
+ * field presence and roles; drafts are edited immutably by path.
+ * @module @qilin-agent/client-schema-form/model
+ */
+import Schema from '@qilin-agent/schemastery';
+/** Live schemastery node; the renderer reads only its structural relations. */
+export type SchemaNode = Schema;
+/**
+ * Rehydrate a serialized schema envelope into a live validator/node tree.
+ * @param serialized - `schema.toJSON()` output received over the wire.
+ * @returns the root schema node.
+ */
+export declare function rehydrateSchema(serialized: unknown): SchemaNode;
+/**
+ * Validate a draft against a rehydrated schema.
+ * @param schema - rehydrated root node.
+ * @param draft - candidate value.
+ * @returns the validation failure message, or `undefined` when the draft passes.
+ */
+export declare function validateDraft(schema: SchemaNode, draft: unknown): string | undefined;
+/**
+ * Resolve the schema node at a settings path (the configurable-provider
+ * directory's `settingsPath` vocabulary): object properties by name, dict
+ * entries through `inner`. An unresolvable segment returns `undefined` so
+ * the caller falls back instead of rendering a wrong subtree.
+ * @param root - rehydrated section root node.
+ * @param path - key path from the section root.
+ * @returns the node describing that position, or `undefined`.
+ */
+export declare function nodeAtPath(root: SchemaNode, path: readonly string[]): SchemaNode | undefined;
+/**
+ * Read a nested value by path.
+ * @param value - root value (draft or fallback layer).
+ * @param path - key path from the root; array indexes as strings.
+ * @returns the value at the path, or `undefined` along a missing branch.
+ */
+export declare function getPath(value: unknown, path: readonly string[]): unknown;
+/**
+ * Whether a draft explicitly carries the path (its presence marks a user
+ * override, independent of the value stored there).
+ * @param value - root value (draft or fallback layer).
+ * @param path - key path from the root; array indexes as strings.
+ * @returns whether the path's final key exists on its parent.
+ */
+export declare function hasPath(value: unknown, path: readonly string[]): boolean;
+/**
+ * Immutably set a nested value, materializing missing intermediate containers.
+ * @param root - draft root (never mutated).
+ * @param path - non-empty key path.
+ * @param value - value to store at the path.
+ * @returns the new draft root.
+ * @throws when `path` is empty.
+ */
+export declare function setPath(root: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown>;
+/**
+ * Immutably remove a nested key (the per-field reset: the resolved value
+ * falls back to the composition base and schema defaults). Removing along a
+ * missing branch returns the root unchanged.
+ * @param root - draft root (never mutated).
+ * @param path - non-empty key path.
+ * @returns the new draft root.
+ * @throws when `path` is empty.
+ */
+export declare function deletePath(root: Record<string, unknown>, path: readonly string[]): Record<string, unknown>;
+//# sourceMappingURL=model.d.ts.map

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@qilin-agent/client-schema-form",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Schema/draft model layer for settings editors: rehydrates a serialized schemastery schema, validates drafts, and edits them immutably by path",
+  "version": "3.1.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/schema-form"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.5"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/schemastery": "~3.18.5"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ]
 }