create-aiaui-module 0.1.0 → 0.1.1-TEST

package/README.md

@@ -1,35 +1,102 @@
-# AIAUI module templates
+# create-aiaui-module
 
-This directory is the source of truth for module starter code. Each subdirectory of `templates/` is named after the generated module ID and contains `contractVersion`, a README, and the module's editable files. `api.py` is optional. Frontend templates include Vue components plus a slot customization contract, a `resources/src/index.ts` bridge with `mount` and `unmount`, and a prebuilt `resources/dist/`.
+在 AIAUI Instance 根目录一键生成可编辑的模块目录（FastAPI 后端路由 + Vue 前端）。
+通过 `npx` 运行，无需全局安装、无需克隆仓库，运行时无外部依赖（除 Instance
+侧已声明的 Python 依赖）。
 
-## Use with npx (no global install)
+| 步骤 | 命令 | 说明 |
+| --- | --- | --- |
+| 查看可用模块 | `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） |
 
-From an Instance root containing `Config/`:
+## 环境要求
+
+- 执行生成器的机器：Node.js >= 20
+- Instance 运行侧：Python + `fastapi`、`uvicorn`（Instance 侧自备，`pip install fastapi uvicorn`）
+
+## 快速开始
+
+在 Instance 根目录（含 `Config/` 的目录）下执行：
 
 ```bash
 npx create-aiaui-module@latest JobInformation
-npx create-aiaui-module@latest --list                 # show available template IDs
-npx create-aiaui-module@latest JobInformation --json  # machine-readable summary
 ```
 
-`npx` fetches the package on demand; nothing needs to be installed globally.
-Use `npx create-aiaui-module@<version>` to pin a specific release.
+生成后 `PyAIAUI/JobInformation/` 与 `PyAIAUI/_runtime/` 就位，`Config/AIAUIProtocol.json` 中登记该模块（默认 `enabled: false`、`port: null`）。
+
+启用前需要调整的配置：
+
+```json
+{
+  "schemaVersion": 1,
+  "port": 18901,
+  "modules": [
+    { "name": "JobInformation", "enabled": true }
+  ]
+}
+```
+
+把 Instance 启动/关闭流程接上（生成后 `PyAIAUI` 目录里就是这段代码的宿主实现）：
+
+```python
+from PyAIAUI import AIAUI
+
+# 业务对象就绪后
+aiaui = AIAUI.start(services={"job_repository": repo})
+# aiaui 为 None 表示没有任何模块启用
+
+# ... Instance 正常运行 ...
+
+# 关闭前
+if aiaui is not None:
+    aiaui.stop()
+```
+
+`AIAUI.start()` 幂等（重复调用返回同一 handle），一个 handle 托管本 Instance 全部启用模块，共用一个 loopback 端口。后端接口由模块自己的 `api.py` 里的 `create_api(context)` 提供，`context.services` 就是上面注入的业务对象。
+
+## 生成结果
+
+```
+<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/                        # 内嵌模块宿主（零外部依赖）
+```
+
+生成器不选端口、不装依赖、不启动进程、不覆盖已存在的模块目录；无效的既有协议会被拒绝且不留残留。
+
+## 内置模块清单
 
-## Local use
+| 模块 ID | 说明 | 组成 |
+| --- | --- | --- |
+| `JobInformation` | 工单 / 载具 / 工序信息面板 | FastAPI 后端 + Vue 前端；内置 `header`、`inputCarriers`、`outputCarriers`、`timeline`、`recipe` 五个可替换槽位；三级定制（默认 / 局部替换 / 全量自定义） |
+| `HelloWorld` | 最小前端模块示例 | 自定义元素；验证挂载链路，无后端 |
+自定义通过 `resources/src/customization.ts` 完成，槽位通信通过 `context.bus`（事件 / expose+peer），详见生成目录里的 `CUSTOMIZATION.md`。
 
-From an Instance root in a checkout:
+## UIService 集成
 
 ```bash
-node /path/to/ServerManageForLiunx/UIModulesTemplate/bin/create-aiaui-module.js --list
-node /path/to/ServerManageForLiunx/UIModulesTemplate/bin/create-aiaui-module.js JobInformation
+npm i -g create-aiaui-module
+export AIA_UI_MODULE_TEMPLATE_ROOT="$(npm root -g)/create-aiaui-module"
 ```
 
-From another directory, pass `--instance-root /path/to/Instance`. Existing `PyAIAUI/<ModuleId>` directories are never overwritten. Generation creates `Config/AIAUIProtocol.json` when absent, with `port: null` and a disabled module entry. If the protocol already exists, it appends a disabled entry without changing its port or other settings. It does not choose a port, install dependencies, or start a process. An invalid existing protocol is rejected without leaving a new module directory.
+此后 UIService 调用包内 `bin/create-aiaui-module.js`（与 `npx` 行为一致），或在业务机上直接 `npx`。
 
-To test the npm snapshot locally, run `npm pack --pack-destination /tmp` here, then use `npm exec --offline --package=/tmp/create-aiaui-module-0.1.0.tgz -- create-aiaui-module --list`.
+## 常用命令
 
-UIService invokes this same script. A deployed UIService needs Node.js (>= 20) and `AIA_UI_MODULE_TEMPLATE_ROOT` pointing to the installed package directory (for example the package installed under `npm root -g`).
+- `npx create-aiaui-module@latest --list` — 查看模板
+- `npx create-aiaui-module@latest <ModuleId>` — 生成（`--instance-root` 指定根目录）
+- `npx create-aiaui-module@latest --json --list` — 机器可读
 
-## Add a template
+## 维护者（发布新模板）
 
-Add `templates/<ModuleId>/` with a `contractVersion` file and a complete editable implementation. If it has a frontend, run `npm install` and `npm run build` from its `resources/` directory, then commit the updated `dist/`. Run `npm test` here and inspect `npm pack --dry-run --json` before packaging a new version.
+- 新增模块：在 `templates/<ModuleId>/` 下放实现（含 `contractVersion`、`README.md`、`resources/`）
+- 前端模板发布前在 `resources/` 跑 `npm install && npm run build`，把产物一起随包发布；发布自动执行 `verify-dist` 校验每个模板的 `contractVersion`、入口、`dist/` 产物
+- 发版流程：`npm test` → 改 `package.json` 版本号 → `npm publish`

package/bin/create-aiaui-module.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -9,6 +10,79 @@ import {
 } from "../src/generator.js";
 
 const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const DIVIDER = "─".repeat(48);
+
+function briefDescription(templateId) {
+  try {
+    const text = readFileSync(
+      path.join(packageRoot, "templates", templateId, "README.md"),
+      "utf8",
+    );
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("---"))
+        continue;
+      // Keep the first sentence so the list stays scannable.
+      const sentence = trimmed.split(/(?<=\.)\s([A-Z])/)[0];
+      const clipped = sentence.length > 120 ? `${sentence.slice(0, 117)}…` : sentence;
+      return clipped.length > 0 ? clipped : trimmed;
+    }
+  } catch {
+    /* template without README simply shows no description */
+  }
+  return "";
+}
+
+function printTemplateList(entries) {
+  console.log();
+  console.log("AIAUI 模块模板");
+  console.log(DIVIDER);
+  if (entries.length === 0) console.log("  (none)");
+  for (const entry of entries) {
+    console.log(`  ${entry.id}  ·  contract v${entry.contractVersion}`);
+    if (briefDescription(entry.id))
+      console.log(`     ${briefDescription(entry.id)}`);
+  }
+  console.log(DIVIDER);
+  console.log("生成: npx create-aiaui-module <模块名> [--list] [--json]");
+}
+
+function printSuccess(result) {
+  console.log();
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("                  [AIAUI] 生成成功");
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log();
+  console.log(`  ✅ 生成路径    ${result.path} (${result.filesCopied} 个文件)`);
+  console.log(`  ✅ 协议配置    ${result.configPath} (enabled: ${result.enabled})`);
+  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();
+}
 
 function parseArgs(args) {
   const options = {
@@ -42,28 +116,18 @@ function parseArgs(args) {
 
 try {
   const options = parseArgs(process.argv.slice(2));
-  const result = options.list
-    ? await listTemplates(packageRoot)
-    : await createModule({
-        templateId: options.templateId,
-        instanceRoot: options.instanceRoot,
-        root: packageRoot,
-      });
-  if (options.json) console.log(JSON.stringify(result));
-  else if (options.list)
-    console.log(
-      result
-        .map((item) => `${item.id} (contract ${item.contractVersion})`)
-        .join("\n"),
-    );
-  else {
-    console.log(`Generated ${result.path} (${result.filesCopied} files)`);
-    console.log(
-      `Registered in ${result.configPath} (enabled: ${result.enabled}, port: ${result.port ?? "unset"})`,
-    );
-    console.log(
-      "Next: call PyAIAUI.start(services={...}) / PyAIAUI.stop() from the Instance lifecycle, set a free port, then enable the module. Generation does not start it.",
-    );
+  if (options.list) {
+    const entries = await listTemplates(packageRoot);
+    if (options.json) console.log(JSON.stringify(entries));
+    else printTemplateList(entries);
+  } else {
+    const result = await createModule({
+      templateId: options.templateId,
+      instanceRoot: options.instanceRoot,
+      root: packageRoot,
+    });
+    if (options.json) console.log(JSON.stringify(result));
+    else printSuccess(result);
   }
 } catch (error) {
   const code =

package/package.json

@@ -1,12 +1,29 @@
 {
   "name": "create-aiaui-module",
-  "version": "0.1.0",
-  "description": "Scaffold AIAUI Instance modules (FastAPI router + editable Vue frontend) via npx",
-  "keywords": ["aiaui", "scaffolding", "generator", "vue", "fastapi", "module", "instance"],
+  "version": "0.1.1-TEST",
+  "description": "AIAUI Instance module scaffolder: generate editable module (FastAPI + Vue frontend) with one npx command",
+  "keywords": [
+    "aiaui",
+    "scaffolding",
+    "generator",
+    "vue",
+    "fastapi",
+    "module",
+    "instance"
+  ],
   "type": "module",
-  "bin": { "create-aiaui-module": "./bin/create-aiaui-module.js" },
-  "files": ["bin", "src", "runtime", "templates"],
-  "engines": { "node": ">=20" },
+  "bin": {
+    "create-aiaui-module": "./bin/create-aiaui-module.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "runtime",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "test": "node tests/generator.test.js",
     "verify-dist": "node scripts/verify-dist.mjs",

package/runtime/__init__.py

@@ -1,39 +1,82 @@
 """Instance-side entry point for enabled AIAUI modules.
 
-The owning Instance calls start() after its business objects are ready and
-stop() before those objects are torn down. Generated modules remain editable;
-this file only delegates discovery and hosting to the inlined ``_runtime``
-package (no external ``aiaui`` dependency is required).
+The owning Instance calls ``AIAUI.start(services={...})`` once its business
+objects are ready and ``aiaui.stop()`` during shutdown. Generated modules
+remain editable; this file only delegates discovery and hosting to the
+inlined ``_runtime`` package (no external ``aiaui`` dependency is required).
+
+Typical use::
+
+    from PyAIAUI import AIAUI
+
+    aiaui = AIAUI.start(services={"job_repository": repo})
+    # ... run the Instance ...
+    aiaui.stop()
+
+``AIAUI.start()`` returns ``None`` when no modules are enabled in
+``Config/AIAUIProtocol.json``.
 """
 
 from pathlib import Path
 
 from ._runtime import attach
 
-_host = None
 
+class AIAUI:
+    """Host handle for one Instance's enabled AIAUI modules.
 
-def start(*, services=None, logger=None):
-    """Start the enabled modules for this Instance, returning their host.
-
-    Pass the Instance's live business objects through ``services`` so module
-    backends (``create_api(context)``) can reach them via ``context.services``.
-    Returns None when no modules are enabled in ``Config/AIAUIProtocol.json``.
+    One handle hosts every enabled module of the Instance on a single
+    loopback HTTP port (see ``Config/AIAUIProtocol.json``). ``start()`` is
+    idempotent per Instance: a second call returns the same handle while the
+    host lives, and ``stop()`` tears everything down.
     """
-    global _host
-    if _host is not None and not _host.closed:
-        return _host
-    _host = attach(
-        Path(__file__).resolve().parent.parent,
-        services=services,
-        logger=logger,
-    )
-    return _host
-
-
-def stop():
-    """Stop the host when the Instance's business objects are shutting down."""
-    global _host
-    host, _host = _host, None
-    if host is not None:
-        host.close()
+
+    _current: "AIAUI | None" = None
+
+    def __init__(self, host):
+        self._host = host
+        self.closed = False
+
+    @classmethod
+    def start(cls, *, services=None, logger=None) -> "AIAUI | None":
+        """Start this Instance's enabled modules and return the handle.
+
+        ``services`` are the Instance's live business objects; every module
+        backend (``create_api(context)``) reaches them through
+        ``context.services``. Returns ``None`` when no modules are enabled.
+
+        ``start()`` never selects a port, installs dependencies, or starts a
+        network socket outside the loopback interface; the port comes from
+        the Instance's ``Config/AIAUIProtocol.json``.
+        """
+        current = cls._current
+        if current is not None and not current.closed:
+            return current
+        host = attach(
+            Path(__file__).resolve().parent.parent,
+            services=services,
+            logger=logger,
+        )
+        if host is None:
+            return None
+        handle = cls(host)
+        cls._current = handle
+        return handle
+
+    @property
+    def host(self):
+        """The underlying loopback host, or ``None`` after ``stop()``.
+
+        Exposed for advanced inspection only; normal code should use
+        ``stop()`` and let this handle the lifecycle.
+        """
+        return None if self.closed else self._host
+
+    def stop(self) -> None:
+        """Stop every module hosted for this Instance (usually at shutdown)."""
+        if self.closed:
+            return
+        self.closed = True
+        self._host.close()
+        if AIAUI._current is self:
+            AIAUI._current = None

package/templates/HelloWorld/README.md

@@ -2,4 +2,12 @@
 
 This frontend-only template shows a minimal AIAUI module. Edit `resources/src/Hello.ce.vue`, then run `npm install` and `npm run build` inside `resources/` to refresh the prebuilt file. `resources/src/index.ts` remains the module entry. There is intentionally no `api.py`.
 
-Generation creates `PyAIAUI/HelloWorld/` and registers it as disabled in `Config/AIAUIProtocol.json`. Set a port and enable it after integrating the module host.
+Generation creates `PyAIAUI/HelloWorld/` and registers it as disabled in `Config/AIAUIProtocol.json`. Set a port and enable it after integrating the module host:
+
+```python
+from PyAIAUI import AIAUI
+
+aiaui = AIAUI.start(services={...})
+# ... later ...
+aiaui.stop()
+```

package/templates/JobInformation/README.md

@@ -84,16 +84,17 @@ For quick iteration, `npm run dev` runs `vite build --watch` and keeps
 Call the generated entry point from your Instance's own startup method:
 
 ```python
-from PyAIAUI import start, stop
+from PyAIAUI import AIAUI
 
 
-host = start(services={
+aiaui = AIAUI.start(services={
     "secs_server": secs_server,
     "job_repository": job_repository,
 })
+# aiaui is None when no modules are enabled
 
 # ... later, during shutdown ...
-stop()
+aiaui.stop()
 ```
 
 `start()` returns `None` when `JobInformation` is disabled in

package/templates/JobInformation/api.py

@@ -8,7 +8,7 @@ from fastapi import APIRouter
 def create_api(context) -> APIRouter:
     """Entry point invoked by the generated PyAIAUI host.
 
-    The Instance injects its live objects via ``PyAIAUI.start(services={...})``
+    The Instance injects its live objects via ``PyAIAUI.AIAUI.start(services={...})``
     and they arrive here through ``context.services``.
     """
     router = APIRouter()