@choiceopen/atomemo-plugin-schema 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Choiceform
+
+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,37 +1,280 @@
-# Choiceform Atomemo Plugin Schema
+# @choiceopen/atomemo-plugin-schema
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+A comprehensive TypeScript type definitions and Zod schema validation library for developing Choiceform Atomemo plugins. This library ensures type safety at compile time and runtime validation for plugin definitions.
+
+## Features
+
+- 🎯 **Type Safety**: Complete TypeScript type definitions for plugin development
+- ✅ **Runtime Validation**: Zod schema validation for plugin definitions
+- 🌍 **i18n Support**: Built-in internationalization text types and validation
+- 🎨 **Flexible Property System**: Support for various data types and UI components
+- 🔧 **Conditional Display**: Conditional display logic based on other property values
+- 📦 **Tree-shakeable**: Optimized exports for minimal bundle size
+
+## Installation
+
+```bash
+# Using npm
+npm install @choiceopen/atomemo-plugin-schema zod
+
+# Using yarn
+yarn add @choiceopen/atomemo-plugin-schema zod
+
+# Using pnpm
+pnpm add @choiceopen/atomemo-plugin-schema zod
+
+# Using bun
+bun add @choiceopen/atomemo-plugin-schema zod
+```
+
+> **Note**: `zod` is a peer dependency and must be installed separately.
+
+## Quick Start
+
+### Import Types
+
+```typescript
+import type {
+  PluginDefinition,
+  CredentialDefinition,
+  DataSourceDefinition,
+  ModelDefinition,
+  ToolDefinition,
+  Property,
+} from '@choiceopen/atomemo-plugin-schema/types';
+```
+
+### Import Schemas
+
+```typescript
+import {
+  PluginDefinitionSchema,
+  CredentialDefinitionSchema,
+  DataSourceDefinitionSchema,
+  ModelDefinitionSchema,
+  ToolDefinitionSchema,
+  PropertySchema,
+} from '@choiceopen/atomemo-plugin-schema/schemas';
+```
+
+### Example: Define a Plugin
+
+```typescript
+import { PluginDefinitionSchema } from '@choiceopen/atomemo-plugin-schema/schemas';
+import type { PluginDefinition } from '@choiceopen/atomemo-plugin-schema/types';
+
+const pluginDefinition: PluginDefinition = {
+  name: 'my-plugin',
+  display_name: {
+    en_US: 'My Plugin',
+    zh_CN: '我的插件',
+  },
+  description: {
+    en_US: 'A sample plugin for Atomemo',
+    zh_CN: '一个示例插件',
+  },
+  icon: 'https://example.com/icon.png',
+  version: '1.0.0',
+  locales: ['en', 'zh_CN'],
+};
+
+// Validate at runtime
+const result = PluginDefinitionSchema.safeParse(pluginDefinition);
+if (!result.success) {
+  console.error('Validation failed:', result.error);
+}
+```
+
+## Core Concepts
+
+### Plugin Definition
+
+A plugin definition contains metadata about your plugin:
+
+- Basic information: name, display name, description, icon
+- Author information: name, email, repository URL, version
+- Supported languages list
+
+### Feature Definitions
+
+Feature definitions include:
+
+- **Credential**: For storing and managing authentication information
+- **DataSource**: For connecting to external data sources
+- **Model**: For defining LLM models
+- **Tool**: For executing specific functions
+
+### Property System
+
+The property system is the core of defining plugin parameters and settings:
+
+**Property Types:**
+- `string`: String type
+- `number` / `integer`: Number type
+- `boolean`: Boolean type
+- `array`: Array type
+- `object`: Object type
+- `discriminated_union`: Discriminated union type
+- `credential_id`: Credential ID type
+- `encrypted_string`: Encrypted string type
+
+**Property Features:**
+- Constant values (`constant`)
+- Default values (`default`)
+- Enum values (`enum`)
+- Range constraints (`min_length`, `max_length`, `minimum`, `maximum`, `min_items`, `max_items`)
+- Conditional display (`display.hide/show`)
+- AI configuration (`ai.llm_description`)
+
+### UI Component System
+
+Each property type can be configured with different UI components:
+
+**String type components:**
+- `input`, `textarea`, `code-editor`
+- `select`, `radio-group`
+- `emoji-picker`, `color-picker`, `credential-select`
+
+**Number type components:**
+- `number-input`, `slider`
+
+**Boolean type components:**
+- `switch`, `checkbox`
+
+**Array type components:**
+- `multi-select`, `tag-input`, `key-value-editor`, `slider`, `array-section`
+
+**Object type components:**
+- `collapsible-panel`, `json-schema-editor`, `conditions-editor`, `code-editor`
+
+### Conditional Display System
+
+Supports conditional display logic based on other property values:
+
+**Operators:**
+- Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
+- Existence check: `$exists`
+- Set operations: `$in`, `$nin`
+- Regex matching: `$regex`, `$options`
+- Array operations: `$size`, `$mod`
+- Logical combination: `$and`, `$or`, `$nor`
+
+## API Reference
+
+### Exports
+
+The package exports two main entry points:
+
+- `@choiceopen/atomemo-plugin-schema/types` - TypeScript type definitions
+- `@choiceopen/atomemo-plugin-schema/schemas` - Zod schema validators
+
+### Development Exports
+
+In development environments, the package exports source files directly for better debugging and hot reload support:
+
+```json
+{
+  "./schemas": {
+    "development": "./src/schemas.ts",
+    "default": "./dist/schemas.js"
+  },
+  "./types": {
+    "development": "./src/types.ts",
+    "default": "./dist/types.js"
+  }
+}
+```
 
 ## Development
 
-- Install dependencies:
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0.0
+- Node.js >= 18.0.0 (if not using Bun)
+
+### Setup
 
 ```bash
+# Install dependencies
 bun install
 ```
 
-- Watch and rebuild in development
+### Available Scripts
 
 ```bash
+# Watch and rebuild in development
 bun run dev
-```
 
-- Linting and formatting
+# Build the library
+bun run build
 
-```bash
+# Run linting and formatting
 bun run check
-```
 
-- Run the unit tests:
+# Run type checking
+bun run typecheck
 
-```bash
+# Run unit tests
 bun run test
 ```
 
-- Build the library:
+### Code Quality
 
-```bash
-bun run build
+This project uses [Biome](https://biomejs.dev) for unified linting and formatting. For the best development experience, install the [Biome VS Code extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome).
+
+## Project Structure
+
+```
+atomemo-plugin-schema/
+├── src/                    # Source code
+│   ├── schemas/           # Zod schema validation modules
+│   ├── types/             # TypeScript type definitions
+│   ├── utils/             # Utility functions
+│   ├── schemas.ts         # Schema exports
+│   └── types.ts           # Type exports
+├── tests/                  # Test files
+├── dist/                  # Build output
+└── [config files]         # package.json, tsconfig.json, etc.
 ```
 
-## Linting and formatting
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+1. Follow the project's code style (use Biome for formatting)
+2. Ensure all tests pass
+3. Ensure type safety (use `IsEqual` for validation)
+4. Update relevant documentation
+5. Run `bun run check` and `bun run test` before submitting
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and linting (`bun run check && bun run test`)
+5. Commit your changes (`git commit -m 'Add some amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a list of changes and version history.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📖 [Documentation](https://github.com/choice-open/atomemo-plugin-schema#readme)
+- 🐛 [Issue Tracker](https://github.com/choice-open/atomemo-plugin-schema/issues)
+- 💬 [Discussions](https://github.com/choice-open/atomemo-plugin-schema/discussions)
+
+## Acknowledgments
 
-This project uses Biome to provide unified linting and formatting, please install VS Code extension if you use VS Code to having the best DX support.
+- Built with [TypeScript](https://www.typescriptlang.org/)
+- Schema validation powered by [Zod](https://zod.dev/)
+- Tool types from [type-fest](https://github.com/sindresorhus/type-fest)

package/README.zh-CN.md

@@ -0,0 +1,280 @@
+# @choiceopen/atomemo-plugin-schema
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+一个全面的 TypeScript 类型定义和 Zod Schema 验证库，用于开发 Choiceform Atomemo 插件。该库确保插件定义在编译时和运行时的类型安全与验证。
+
+## 特性
+
+- 🎯 **类型安全**: 完整的 TypeScript 类型定义，支持插件开发
+- ✅ **运行时验证**: 使用 Zod Schema 进行运行时验证
+- 🌍 **国际化支持**: 内置国际化文本类型和验证
+- 🎨 **灵活的属性系统**: 支持多种数据类型和 UI 组件
+- 🔧 **条件显示**: 基于其他属性值的条件显示逻辑
+- 📦 **Tree-shakeable**: 优化的导出，最小化打包体积
+
+## 安装
+
+```bash
+# 使用 npm
+npm install @choiceopen/atomemo-plugin-schema zod
+
+# 使用 yarn
+yarn add @choiceopen/atomemo-plugin-schema zod
+
+# 使用 pnpm
+pnpm add @choiceopen/atomemo-plugin-schema zod
+
+# 使用 bun
+bun add @choiceopen/atomemo-plugin-schema zod
+```
+
+> **注意**: `zod` 是 peer dependency，需要单独安装。
+
+## 快速开始
+
+### 导入类型
+
+```typescript
+import type {
+  PluginDefinition,
+  CredentialDefinition,
+  DataSourceDefinition,
+  ModelDefinition,
+  ToolDefinition,
+  Property,
+} from '@choiceopen/atomemo-plugin-schema/types';
+```
+
+### 导入 Schema
+
+```typescript
+import {
+  PluginDefinitionSchema,
+  CredentialDefinitionSchema,
+  DataSourceDefinitionSchema,
+  ModelDefinitionSchema,
+  ToolDefinitionSchema,
+  PropertySchema,
+} from '@choiceopen/atomemo-plugin-schema/schemas';
+```
+
+### 示例：定义一个插件
+
+```typescript
+import { PluginDefinitionSchema } from '@choiceopen/atomemo-plugin-schema/schemas';
+import type { PluginDefinition } from '@choiceopen/atomemo-plugin-schema/types';
+
+const pluginDefinition: PluginDefinition = {
+  name: 'my-plugin',
+  display_name: {
+    en_US: 'My Plugin',
+    zh_CN: '我的插件',
+  },
+  description: {
+    en_US: 'A sample plugin for Atomemo',
+    zh_CN: '一个示例插件',
+  },
+  icon: 'https://example.com/icon.png',
+  version: '1.0.0',
+  locales: ['en', 'zh_CN'],
+};
+
+// 运行时验证
+const result = PluginDefinitionSchema.safeParse(pluginDefinition);
+if (!result.success) {
+  console.error('验证失败:', result.error);
+}
+```
+
+## 核心概念
+
+### 插件定义
+
+插件定义包含插件的元数据：
+
+- 基本信息：名称、显示名称、描述、图标
+- 作者信息：名称、邮箱、仓库 URL、版本
+- 支持的语言列表
+
+### 功能定义
+
+功能定义包括：
+
+- **Credential（凭证）**: 用于存储和管理认证信息
+- **DataSource（数据源）**: 用于连接外部数据源
+- **Model（模型）**: 用于定义 LLM 模型
+- **Tool（工具）**: 用于执行特定功能
+
+### 属性系统
+
+属性系统是定义插件参数和设置的核心：
+
+**属性类型：**
+- `string`: 字符串类型
+- `number` / `integer`: 数字类型
+- `boolean`: 布尔类型
+- `array`: 数组类型
+- `object`: 对象类型
+- `discriminated_union`: 区分联合类型
+- `credential_id`: 凭证 ID 类型
+- `encrypted_string`: 加密字符串类型
+
+**属性特性：**
+- 常量值（`constant`）
+- 默认值（`default`）
+- 枚举值（`enum`）
+- 范围限制（`min_length`、`max_length`、`minimum`、`maximum`、`min_items`、`max_items`）
+- 条件显示（`display.hide/show`）
+- AI 配置（`ai.llm_description`）
+
+### UI 组件系统
+
+每个属性类型可以配置不同的 UI 组件：
+
+**字符串类型可用组件：**
+- `input`、`textarea`、`code-editor`
+- `select`、`radio-group`
+- `emoji-picker`、`color-picker`、`credential-select`
+
+**数字类型可用组件：**
+- `number-input`、`slider`
+
+**布尔类型可用组件：**
+- `switch`、`checkbox`
+
+**数组类型可用组件：**
+- `multi-select`、`tag-input`、`key-value-editor`、`slider`、`array-section`
+
+**对象类型可用组件：**
+- `collapsible-panel`、`json-schema-editor`、`conditions-editor`、`code-editor`
+
+### 条件显示系统
+
+支持基于其他属性值的条件显示逻辑：
+
+**操作符：**
+- 比较操作符：`$eq`、`$ne`、`$gt`、`$gte`、`$lt`、`$lte`
+- 存在性检查：`$exists`
+- 集合操作：`$in`、`$nin`
+- 正则匹配：`$regex`、`$options`
+- 数组操作：`$size`、`$mod`
+- 逻辑组合：`$and`、`$or`、`$nor`
+
+## API 参考
+
+### 导出
+
+包导出两个主要入口点：
+
+- `@choiceopen/atomemo-plugin-schema/types` - TypeScript 类型定义
+- `@choiceopen/atomemo-plugin-schema/schemas` - Zod Schema 验证器
+
+### 开发环境导出
+
+在开发环境中，包直接导出源文件，以便更好地调试和支持热重载：
+
+```json
+{
+  "./schemas": {
+    "development": "./src/schemas.ts",
+    "default": "./dist/schemas.js"
+  },
+  "./types": {
+    "development": "./src/types.ts",
+    "default": "./dist/types.js"
+  }
+}
+```
+
+## 开发
+
+### 前置要求
+
+- [Bun](https://bun.sh) >= 1.0.0
+- Node.js >= 18.0.0（如果不使用 Bun）
+
+### 设置
+
+```bash
+# 安装依赖
+bun install
+```
+
+### 可用脚本
+
+```bash
+# 开发模式监听并重新构建
+bun run dev
+
+# 构建库
+bun run build
+
+# 运行代码检查和格式化
+bun run check
+
+# 运行类型检查
+bun run typecheck
+
+# 运行单元测试
+bun run test
+```
+
+### 代码质量
+
+本项目使用 [Biome](https://biomejs.dev) 进行统一的代码检查和格式化。为了获得最佳的开发体验，请安装 [Biome VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)。
+
+## 项目结构
+
+```
+atomemo-plugin-schema/
+├── src/                    # 源代码
+│   ├── schemas/           # Zod Schema 验证模块
+│   ├── types/             # TypeScript 类型定义
+│   ├── utils/             # 工具函数
+│   ├── schemas.ts         # Schema 导出
+│   └── types.ts           # 类型导出
+├── tests/                  # 测试文件
+├── dist/                  # 构建输出
+└── [配置文件]             # package.json, tsconfig.json 等
+```
+
+## 贡献
+
+欢迎贡献！请遵循以下指南：
+
+1. 遵循项目的代码风格（使用 Biome 进行格式化）
+2. 确保所有测试通过
+3. 确保类型安全（使用 `IsEqual` 进行验证）
+4. 更新相关文档
+5. 提交前运行 `bun run check` 和 `bun run test`
+
+### 开发工作流
+
+1. Fork 仓库
+2. 创建功能分支（`git checkout -b feature/amazing-feature`）
+3. 进行更改
+4. 运行测试和代码检查（`bun run check && bun run test`）
+5. 提交更改（`git commit -m '添加一些很棒的功能'`）
+6. 推送到分支（`git push origin feature/amazing-feature`）
+7. 打开 Pull Request
+
+## 变更日志
+
+查看 [CHANGELOG.md](./CHANGELOG.md) 了解变更列表和版本历史。
+
+## 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
+
+## 支持
+
+- 📖 [文档](https://github.com/choice-open/atomemo-plugin-schema#readme)
+- 🐛 [问题追踪](https://github.com/choice-open/atomemo-plugin-schema/issues)
+- 💬 [讨论](https://github.com/choice-open/atomemo-plugin-schema/discussions)
+
+## 致谢
+
+- 使用 [TypeScript](https://www.typescriptlang.org/) 构建
+- Schema 验证由 [Zod](https://zod.dev/) 提供支持
+- 工具类型来自 [type-fest](https://github.com/sindresorhus/type-fest)