create-aiaui-module 0.2.0 → 0.4.0

package/README.md

@@ -1,103 +1,83 @@
-# create-aiaui-module
+# AIAUI module templates
 
-在 AIAUI Instance 根目录一键生成可编辑的模块目录（FastAPI 后端路由 + Vue 前端）。
-通过 `npx` 运行，无需全局安装、无需克隆仓库，运行时无外部依赖（除 Instance
-侧已声明的 Python 依赖）。
+Scaffold an editable AIAUI Instance module — a FastAPI `backend/` router
+plus a Vue `client/` frontend — with a single `npx` command. No global
+install, no repository checkout, no `aiaui` package required.
 
-| 步骤 | 命令 | 说明 |
+| Step | Command | Description |
 | --- | --- | --- |
-| 查看可用模块 | `npx create-aiaui-module@latest --list` | 列出模块 ID 与 contractVersion |
-| 生成模块 | `npx create-aiaui-module@latest JobDashboard` | 在实例根目录生成 `PyAIAUI/JobDashboard` |
-| 机器可读 | `npx create-aiaui-module@latest JobDashboard --json` | 生成结果输出 JSON（接 CI） |
+| List available templates | `npx create-aiaui-module@latest --list` | Allowed template IDs and their contract version |
+| Create a module | `npx create-aiaui-module@latest JobDashboard` | Generates `PyAIAUI/JobDashboard/` in the Instance root |
+| Machine-readable output | `npx create-aiaui-module@latest JobDashboard --json` | Structured result (CI hook) |
 
-## 环境要求
+## Requirements
 
-- 执行生成器的机器：Node.js >= 20
-- Instance 运行侧：Python + `fastapi`、`uvicorn`（Instance 侧自备，`pip install fastapi uvicorn`）
+- To run the generator: Node.js >= 20
+- To run the generated module: Python + `fastapi`, `uvicorn` on the Instance
+  side (`pip install fastapi uvicorn`)
 
-## 快速开始
+## Quick start
 
-在 Instance 根目录（含 `Config/` 的目录）下执行：
+From an Instance root (a directory containing `Config/`):
 
 ```bash
 npx create-aiaui-module@latest JobDashboard
 ```
 
-生成后 `PyAIAUI/JobDashboard/` 与 `PyAIAUI/_runtime/` 就位，`Config/AIAUIProtocol.json` 中登记该模块（默认 `enabled: false`、`port: null`）。
+Produces `PyAIAUI/JobDashboard/` (module code) and `PyAIAUI/_runtime/` (the
+embedded runtime that loads it), and registers `JobDashboard` (disabled,
+`port: null`) in `Config/AIAUIProtocol.json`.
 
-启用前需要调整的配置：
+The generated module:
 
-```json
-{
-  "schemaVersion": 1,
-  "port": 18901,
-  "modules": [
-    { "name": "JobDashboard", "enabled": true }
-  ]
-}
+```
+<Instance root>/
+├── Config/AIAUIProtocol.json          # port + module enable/disable
+└── PyAIAUI/
+    ├── __init__.py                    # AIAUI class entry (start/stop)
+    ├── JobDashboard/                  # one module = one directory
+    │   ├── backend/api.py             # create_api(context) -> APIRouter
+    │   ├── backend/config.json        # panel appearance (display + state color/icon)
+    │   ├── client/src/                # Vue frontend source
+    │   ├── client/dist/               # prebuilt bundle (manifest.json)
+    │   └── README.md / CUSTOMIZATION.md
+    └── _runtime/                      # embedded runtime (no external deps)
 ```
 
-把 Instance 启动/关闭流程接上（生成后 `PyAIAUI` 目录里就是这段代码的宿主实现）：
+Enable the module before first boot: pick a free loopback `port` for
+`AIAUIProtocol.json` and flip `enabled` to `true`. Then wire the Instance
+lifecycle:
 
 ```python
 from PyAIAUI import AIAUI
 
-# 业务对象就绪后
 aiaui = AIAUI.start(services={"job_repository": repo})
-# aiaui 为 None 表示没有任何模块启用
-
-# ... Instance 正常运行 ...
-
-# 关闭前
-if aiaui is not None:
-    aiaui.stop()
+...
+aiaui.stop()
 ```
 
-`AIAUI.start()` 幂等（重复调用返回同一 handle），一个 handle 托管本 Instance 全部启用模块，共用一个 loopback 端口。后端接口由模块自己的 `api.py` 里的 `create_api(context)` 提供，`context.services` 就是上面注入的业务对象。
+`AIAUI.start()` is idempotent; it returns `None` when no modules are enabled.
 
-## 生成结果
+After enabling, the module answers locally under
+`/api/v1/services/<id>/modules/JobDashboard/...` (via UIService) — `GET /jobs`
+(feed the panel), `GET /config` (panel appearance from `backend/config.json`),
+and any custom routes you add to `create_api(context)`.
 
-```
-<Instance root>/
-├── Config/AIAUIProtocol.json            # 运行协议：端口 + 模块启停（生成器只登记，不配置）
-└── PyAIAUI/
-    ├── __init__.py                      # 入口：AIAUI 类（AIAUI.start / aiaui.stop）
-    ├── JobDashboard/                   # 模块目录，目录名 == 模块 ID
-    │   ├── backend/api.py               # 后端契约：create_api(context) -> APIRouter
-    │   ├── backend/config.json          # 外观配置（可无：/config 端点读它）
-    │   ├── client/src/                  # Vue 前端源码
-    │   ├── client/dist/                 # 预构建产物（开箱即跑，改源码后 npm run build 重出）
-    │   └── {README.md, CUSTOMIZATION.md}# 模块说明与定制手册
-    └── _runtime/                        # 内嵌模块宿主（零外部依赖）
-```
+## Built-in templates
 
-生成器不选端口、不装依赖、不启动进程、不覆盖已存在的模块目录；无效的既有协议会被拒绝且不留残留。
-
-## 内置模块清单
-
-| 模块 ID | 说明 | 组成 |
+| ID | Description | Contents |
 | --- | --- | --- |
-| `JobDashboard` | 工单 / 载具 / 工序信息面板 | FastAPI 后端（`backend/api.py` + `backend/config.json`）+ Vue 前端（`client/`）；实现 `GET /jobs`（工单数据）+ `GET /config`（显示开关 + 状态色/图标，config.json 读取）即可；分粒度槽位（`board`/`headerRegion`/`middleRegion`/`bottomRegion` + 叶子）可替换任意局部 |
-| `HelloWorld` | 最小前端模块示例 | 自定义元素；验证挂载链路，无后端 |
-自定义通过 `client/src/customization.ts` 完成，槽位通信通过 `context.bus`（事件 / expose+peer），详见生成目录里的 `CUSTOMIZATION.md`。
-
-## UIService 集成
-
-```bash
-npm i -g create-aiaui-module
-export AIA_UI_MODULE_TEMPLATE_ROOT="$(npm root -g)/create-aiaui-module"
-```
-
-此后 UIService 调用包内 `bin/create-aiaui-module.js`（与 `npx` 行为一致），或在业务机上直接 `npx`。
-
-## 常用命令
+| `JobDashboard` | Job information / carrier / process panel | `backend/api.py` + `backend/config.json` + Vue `client/`. Implement `GET /jobs` (job data) and `GET /config` (display switches + state color/icon), or adjust nothing at all — a built-in default panel ships and falls back to demo data. Slots are individually replaceable (`board` / `headerRegion` / `middleRegion` / `bottomRegion` + leaf slots like `jobName` / `status` / `timeline` / `inputCarriers` / `outputCarriers` / `recipe`) without touching the panel shell. |
+| `HelloWorld` | Minimal frontend-only example | Custom element for probing the module lifecycle, no backend |
 
-- `npx create-aiaui-module@latest --list` — 查看模板
-- `npx create-aiaui-module@latest <ModuleId>` — 生成（`--instance-root` 指定根目录）
-- `npx create-aiaui-module@latest --json --list` — 机器可读
+Customize a card's layout by editing `client/src/customization.ts`; every slot
+component receives `{ context, job, config }` as props. See
+`CUSTOMIZATION.md` inside the generated `JobDashboard/` directory for the full
+slot table and contract.
 
-## 维护者（发布新模板）
+## What the generator does NOT do
 
-- 新增模块：在 `templates/<ModuleId>/` 下放实现（含 `contractVersion`、`README.md`、`backend/api.py`、`client/`）
-- 前端模板发布前在 `resources/` 跑 `npm install && npm run build`，把产物一起随包发布；发布自动执行 `verify-dist` 校验每个模板的 `contractVersion`、入口、`dist/` 产物
-- 发版流程：`npm test` → 改 `package.json` 版本号 → `npm publish`
+- It does not choose a port, install dependencies, start any process, or
+  overwrite an existing `PyAIAUI/<ModuleId>` directory.
+- An invalid existing `AIAUIProtocol.json` is refused without leaving a new
+  module directory behind.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-aiaui-module",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AIAUI Instance module scaffolder: npx generates an editable module",
   "keywords": [
     "aiaui",

package/runtime/_runtime/registry.py

@@ -18,7 +18,11 @@ class ModuleDescriptor:
     def __init__(self, module_id: str, directory: Path):
         self.id = module_id
         self.directory = directory
-        self.api_file = directory / "api.py"
+        # New templates ship backend/api.py, legacy ones api.py at module root.
+        backend_api = directory / "backend" / "api.py"
+        self.api_file = (
+            backend_api if backend_api.is_file() else directory / "api.py"
+        )
         client_dist = directory / "client" / "dist"
         self.frontend_entry = (
             client_dist if client_dist.is_dir() else directory / "resources" / "dist"

package/templates/JobDashboard/backend/api.py

@@ -1,7 +1,6 @@
 """Editable JobDashboard example, mounted under /modules/JobDashboard."""
 
 import inspect
-
 import json
 from pathlib import Path
 
@@ -11,69 +10,49 @@ CONFIG_PATH = Path(__file__).resolve().parent / "config.json"
 
 DEFAULT_CONFIG = {
     "display": {
-        "lotId": true,
-        "recipe": true,
-        "inputCarriers": true,
-        "outputCarriers": true,
-        "timeline": true
+        "lotId": True,
+        "recipe": True,
+        "inputCarriers": True,
+        "outputCarriers": True,
+        "timeline": True,
     },
     "states": [
-        {
-            "name": "Setup",
-            "color": "#0369a1",
-            "icon": "clock"
-        },
-        {
-            "name": "Select",
-            "color": "#526176",
-            "icon": "list"
-        },
-        {
-            "name": "WaitingForStart",
-            "color": "#8b95a5",
-            "icon": "stop"
-        },
-        {
-            "name": "Executing",
-            "color": "#1d4ed8",
-            "icon": "activity"
-        },
-        {
-            "name": "Running",
-            "color": "#1d4ed8",
-            "icon": "activity"
-        },
-        {
-            "name": "Complete",
-            "color": "#166534",
-            "icon": "flag"
-        },
-        {
-            "name": "Finished",
-            "color": "#166534",
-            "icon": "flag"
-        }
-    ]
-
+        {"name": "Setup", "color": "#0369a1", "icon": "clock"},
+        {"name": "Select", "color": "#526176", "icon": "list"},
+        {"name": "WaitingForStart", "color": "#8b95a5", "icon": "stop"},
+        {"name": "Executing", "color": "#1d4ed8", "icon": "activity"},
+        {"name": "Running", "color": "#1d4ed8", "icon": "activity"},
+        {"name": "Complete", "color": "#166534", "icon": "flag"},
+        {"name": "Finished", "color": "#166534", "icon": "flag"},
+    ],
 }
 
 
 def default_config() -> dict:
-    """Merge ``config.json`` over the shipped default palette."""
+    """Merge ``config.json`` over the shipped default palette.
+
+    Any missing key is merged over the built-in defaults; unreadable or
+    non-object content falls back to the shipped defaults, so the endpoint
+    can be left ``{}`` to keep everything visible by default.
+    """
     try:
         raw = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
     except OSError:
         return DEFAULT_CONFIG
     if not isinstance(raw, dict):
         return DEFAULT_CONFIG
-    return {**DEFAULT_CONFIG, **raw}
+    merged: dict = {**DEFAULT_CONFIG, **raw}
+    if isinstance(raw.get("display"), dict):
+        merged["display"] = {**DEFAULT_CONFIG["display"], **raw["display"]}
+    if isinstance(raw.get("states"), list) and raw["states"]:
+        merged["states"] = raw["states"]
+    return merged
 
 
 def create_api(context) -> APIRouter:
     """Entry point invoked by the generated PyAIAUI host.
 
-    The Instance injects its live objects via ``PyAIAUI.AIAUI.start(services={...})``
-    and they arrive here through ``context.services``.
+    The Instance injects its live objects via ``PyAIAUI.AIAUI.start(services={...})`` and they arrive here through ``context.services``.
     """
     router = APIRouter()
 
@@ -135,9 +114,8 @@ def create_api(context) -> APIRouter:
 
     @router.get("/config")
     async def config():
-        """Panel appearance contract, read from ``config.json`` (sitting next
-        to this file). Any missing key is merged over the built-in default
-        palette; unreadable/malformed content falls back to the default.
+        """Panel appearance contract, read from ``config.json`` (this file's
+        sibling). Missing keys fall back to the built-in DEFAULT_CONFIG.
         """
         return default_config()
 

package/templates/JobDashboard/backend/config.json

@@ -1,46 +1,3 @@
 {
-  "display": {
-    "lotId": true,
-    "recipe": true,
-    "inputCarriers": true,
-    "outputCarriers": true,
-    "timeline": true
-  },
-  "states": [
-    {
-      "name": "Setup",
-      "color": "#0369a1",
-      "icon": "clock"
-    },
-    {
-      "name": "Select",
-      "color": "#526176",
-      "icon": "list"
-    },
-    {
-      "name": "WaitingForStart",
-      "color": "#8b95a5",
-      "icon": "stop"
-    },
-    {
-      "name": "Executing",
-      "color": "#1d4ed8",
-      "icon": "activity"
-    },
-    {
-      "name": "Running",
-      "color": "#1d4ed8",
-      "icon": "activity"
-    },
-    {
-      "name": "Complete",
-      "color": "#166534",
-      "icon": "flag"
-    },
-    {
-      "name": "Finished",
-      "color": "#166534",
-      "icon": "flag"
-    }
-  ]
-}
+    "display": {}
+}

package/templates/JobDashboard/client/package-lock.json

@@ -1,10 +1,10 @@
 {
-  "name": "aiaui-job-information-template",
+  "name": "aiaui-job-dashboard-template",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "aiaui-job-information-template",
+      "name": "aiaui-job-dashboard-template",
       "dependencies": {
         "vue": "^3.5.0"
       },

package/templates/JobDashboard/client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "aiaui-job-information-template",
+  "name": "aiaui-job-dashboard-template",
   "private": true,
   "type": "module",
   "scripts": {

package/templates/JobDashboard/client/src/defaults/styles.css

@@ -3,7 +3,6 @@
 .legacy-jobs {
   display: grid;
   gap: 20px;
-  padding: 28px;
 }
 
 .legacy-toolbar {