create-aiaui-module 0.1.2-TEST → 0.3.0

package/README.md

@@ -1,102 +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 JobInformation` | 在实例根目录生成 `PyAIAUI/JobInformation` |
-| 机器可读 | `npx create-aiaui-module@latest JobInformation --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 JobInformation
+npx create-aiaui-module@latest JobDashboard
 ```
 
-生成后 `PyAIAUI/JobInformation/` 与 `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": "JobInformation", "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）
-    ├── JobInformation/                  # 模块目录，目录名 == 模块 ID
-    │   ├── api.py                       # 后端契约：create_api(context) -> APIRouter
-    │   ├── resources/src/               # Vue 前端源码
-    │   ├── resources/dist/              # 预构建产物（开箱即跑，改源码后 npm run build 重出）
-    │   └── {README.md, CUSTOMIZATION.md}# 模块说明与定制手册
-    └── _runtime/                        # 内嵌模块宿主（零外部依赖）
-```
+## Built-in templates
 
-生成器不选端口、不装依赖、不启动进程、不覆盖已存在的模块目录；无效的既有协议会被拒绝且不留残留。
-
-## 内置模块清单
-
-| 模块 ID | 说明 | 组成 |
+| ID | Description | Contents |
 | --- | --- | --- |
-| `JobInformation` | 工单 / 载具 / 工序信息面板 | FastAPI 后端 + Vue 前端；内置 `header`、`inputCarriers`、`outputCarriers`、`timeline`、`bottom`（含嵌套的 `recipe`）可替换槽位；三级定制（默认 / 局部替换 / 全量自定义） |
-| `HelloWorld` | 最小前端模块示例 | 自定义元素；验证挂载链路，无后端 |
-自定义通过 `resources/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`、`resources/`）
-- 前端模板发布前在 `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/bin/create-aiaui-module.js

@@ -35,7 +35,7 @@ function briefDescription(templateId) {
 
 function printTemplateList(entries) {
   console.log();
-  console.log("AIAUI 模块模板");
+  console.log("AIAUI module templates");
   console.log(DIVIDER);
   if (entries.length === 0) console.log("  (none)");
   for (const entry of entries) {
@@ -44,43 +44,35 @@ function printTemplateList(entries) {
       console.log(`     ${briefDescription(entry.id)}`);
   }
   console.log(DIVIDER);
-  console.log("生成: npx create-aiaui-module <模块名> [--list] [--json]");
+  console.log("usage: npx create-aiaui-module <ModuleId> [--list] [--json] [--instance-root <path>]");
 }
 
 function printSuccess(result) {
   console.log();
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("                  [AIAUI] 生成成功");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  console.log("                    [AIAUI] module created");
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
   console.log();
-  console.log(`  ✅ 生成路径    ${result.path} (${result.filesCopied} 个文件)`);
-  console.log(`  ✅ 协议配置    ${result.configPath} (enabled: ${result.enabled})`);
+  console.log(`  done  module     ${result.moduleId}`);
+  console.log(`  done  path       ${result.path}`);
+  console.log(`  done  files      ${result.filesCopied}`);
+  console.log(`  done  protocol   ${result.configPath}`);
+  console.log(`                 enabled: ${result.enabled}, port: ${result.port ?? "unset"}`);
   console.log();
-  console.log("⚠️ 配置调整（需要你手动做）");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("  📌 修改 port 字段为 18901（或你选择的其他空闲端口）");
-  console.log("  📌 将 enabled 改为 true");
-  console.log("  📌 模块接入 Instance 启动流程后再启用");
-  console.log();
-  console.log("🔧 接下来要做：");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("  1. 配置端口");
-  console.log("     修改 AIAUIProtocol.json 中 port 字段为 18901（示例值）");
-  console.log("  2. 配置模块 enable");
-  console.log("     修改 AIAUIProtocol.json 中对应模块的 enabled 为 true");
-  console.log("  3. 接入 Instance 启动流程");
-  console.log("     · 启动时: aiaui = AIAUI.start(services={...})");
-  console.log("     · 关闭时: aiaui.stop()");
-  console.log("  4. 打开 UIClient 对应页面查看效果（JobInformation → /jobs）");
-  console.log();
-  console.log("❌ 没有做的（请确认）");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("  · 未启动服务（由 Instance 生命周期调用 AIAUI.start）");
-  console.log("  · 未安装依赖（模块运行需要 pip install fastapi uvicorn）");
-  console.log("  · 未选择/配置端口");
-  console.log("  · 未手动启用任何模块");
-  console.log();
-  console.log("  初始化目录已就绪，按上面的顺序操作即可上线。");
+  console.log("next: edit your Config & wire the module (you must do this)");
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  console.log('  1. Set a free loopback port in AIAUIProtocol.json ("port", e.g. 18900-18999 range)');
+  console.log('     and flip "enabled" to true for your module');
+  console.log("  2. Wire the module into your Instance lifecycle");
+  console.log("     from PyAIAUI import AIAUI");
+  console.log("     aiaui = AIAUI.start(services={...})   # at Instance startup");
+  console.log("     aiaui.stop()                            # at shutdown");
+  console.log('  3. Mount its data: backend/api.py implements create_api(context) -> APIRouter.');
+  console.log("     (many templates ship backend/config.json for appearance settings — see README)");
+
+  console.log("  4. Rebuild the frontend if you edited it:");
+  console.log("     npm install && npm run build        # from <module>/client");
+  console.log("  no  starting services, auto-required deps, or a running Instance is triggered");
   console.log();
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-aiaui-module",
-  "version": "0.1.2-TEST",
-  "description": "AIAUI Instance module scaffolder: generate editable module (FastAPI + Vue frontend) with one npx command",
+  "version": "0.3.0",
+  "description": "AIAUI Instance module scaffolder: npx generates an editable module",
   "keywords": [
     "aiaui",
     "scaffolding",
@@ -9,7 +9,8 @@
     "vue",
     "fastapi",
     "module",
-    "instance"
+    "instance",
+    "sharetek"
   ],
   "type": "module",
   "bin": {

package/runtime/_runtime/registry.py

@@ -18,8 +18,15 @@ class ModuleDescriptor:
     def __init__(self, module_id: str, directory: Path):
         self.id = module_id
         self.directory = directory
-        self.api_file = directory / "api.py"
-        self.frontend_entry = directory / "resources" / "dist"
+        # 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"
+        )
 
     @property
     def has_backend(self) -> bool:

package/templates/{JobInformation → JobDashboard}/CUSTOMIZATION.md

@@ -1,4 +1,4 @@
-# JobInformation customization
+# JobDashboard customization
 
 This module ships a built-in job-information panel that reads two local
 endpoints and renders one card per job. Every part of a card can be replaced
@@ -67,7 +67,7 @@ without touching the platform code; the host contract
 
 ## Slots (what you can replace)
 
-Edit `resources/src/customization.ts`. Keys per card:
+Edit `client/src/customization.ts`. Keys per card:
 
 | Slot | Replaces | Renders inside |
 | --- | --- | --- |
@@ -89,7 +89,7 @@ slots ignore the region around them (which stays platform-owned). Replacing
 sub-slots if set.
 
 ```ts
-// resources/src/customization.ts
+// client/src/customization.ts
 import MyJobName from "./custom/MyJobName.vue";
 import type { Customization } from "./contract";
 

package/templates/{JobInformation → JobDashboard}/README.md

@@ -1,4 +1,4 @@
-# JobInformation module
+# JobDashboard module
 
 This template scaffolds an editable "job information" UI module. The
 generator only produces scaffolding plus an inlined runtime
@@ -19,7 +19,7 @@ def create_api(context) -> APIRouter:
 ```
 
 The generated host calls `create_api(context)` once and mounts the returned
-router at `/modules/JobInformation`. You receive:
+router at `/modules/JobDashboard`. You receive:
 
 - `context.instance_root` — the Instance root directory.
 - `context.services` — a dict of the live objects your Instance passes in at
@@ -40,11 +40,11 @@ Everything else about how to fetch or present data is yours to implement.
 
 The frontend is organized around a small customization contract:
 
-- `resources/src/index.ts` — the stable `mount` / `unmount` bridge the host loads.
-- `resources/src/contract.ts` — the shared types for the module context, bus, and customization.
-- `resources/src/customization.ts` — the only file you normally edit to customize.
-- `resources/src/bus.ts` — a per-mount communication bus shared by all slot components.
-- `resources/src/defaults/` — the built-in panel and its replaceable boxes.
+- `client/src/index.ts` — the stable `mount` / `unmount` bridge the host loads.
+- `client/src/contract.ts` — the shared types for the module context, bus, and customization.
+- `client/src/customization.ts` — the only file you normally edit to customize.
+- `client/src/bus.ts` — a per-mount communication bus shared by all slot components.
+- `client/src/defaults/` — the built-in panel and its replaceable boxes.
 
 Slot components also communicate through `context.bus` (events or imperative handles); see CUSTOMIZATION.md for the patterns.
 
@@ -59,7 +59,7 @@ Three levels are supported without changing `index.ts`:
 2. **Partial** — replace one or more named boxes:
 
    ```ts
-   // resources/src/customization.ts
+   // client/src/customization.ts
    import MyHeader from "./custom/MyHeader.vue";
    import type { Customization } from "./contract";
 
@@ -110,7 +110,7 @@ aiaui = AIAUI.start(services={
 aiaui.stop()
 ```
 
-`start()` returns `None` when `JobInformation` is disabled in
+`start()` returns `None` when `JobDashboard` is disabled in
 `Config/AIAUIProtocol.json`; otherwise it returns the running host.
 
 ## Dependencies (reminder, not installed automatically)

package/templates/{JobInformation → JobDashboard/backend}/api.py

@@ -1,15 +1,58 @@
-"""Editable Job Information example, mounted under /modules/JobInformation."""
+"""Editable JobDashboard example, mounted under /modules/JobDashboard."""
 
 import inspect
+import json
+from pathlib import Path
 
 from fastapi import APIRouter
 
+CONFIG_PATH = Path(__file__).resolve().parent / "config.json"
+
+DEFAULT_CONFIG = {
+    "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"},
+    ],
+}
+
+
+def default_config() -> dict:
+    """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
+    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()
 
@@ -71,27 +114,9 @@ def create_api(context) -> APIRouter:
 
     @router.get("/config")
     async def config():
-        """Panel appearance contract: which parts to display + the state
-        colour/icon map. The template already ships a built-in default copy
-        (``config-defaults.ts``), so this endpoint can stay absent.
+        """Panel appearance contract, read from ``config.json`` (this file's
+        sibling). Missing keys fall back to the built-in DEFAULT_CONFIG.
         """
-        return {
-            "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"},
-            ],
-        }
+        return default_config()
 
     return router

package/templates/JobDashboard/backend/config.json

@@ -0,0 +1 @@
+{"display": {"lotId": false}}

package/templates/{JobInformation/resources → JobDashboard/client}/src/defaults/DefaultPanel.vue

@@ -80,7 +80,7 @@ const visibleJobs = computed(() =>
 </script>
 
 <template>
-  <section class="legacy-jobs" aria-label="Job Information">
+  <section class="legacy-jobs" aria-label="Job Dashboard">
     <header class="legacy-toolbar">
       <div class="legacy-filters">
         <label class="legacy-search">