create-aiaui-module 0.0.0-stage → 0.1.1-TEST

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# create-aiaui-module
 
-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.
+在 AIAUI Instance 根目录一键生成可编辑的模块目录（FastAPI 后端路由 + Vue 前端）。
+通过 `npx` 运行，无需全局安装、无需克隆仓库，运行时无外部依赖（除 Instance
+侧已声明的 Python 依赖）。
+
+| 步骤 | 命令 | 说明 |
+| --- | --- | --- |
+| 查看可用模块 | `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） |
+
+## 环境要求
+
+- 执行生成器的机器：Node.js >= 20
+- Instance 运行侧：Python + `fastapi`、`uvicorn`（Instance 侧自备，`pip install fastapi uvicorn`）
+
+## 快速开始
+
+在 Instance 根目录（含 `Config/` 的目录）下执行：
+
+```bash
+npx create-aiaui-module@latest JobInformation
+```
+
+生成后 `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/                        # 内嵌模块宿主（零外部依赖）
+```
+
+生成器不选端口、不装依赖、不启动进程、不覆盖已存在的模块目录；无效的既有协议会被拒绝且不留残留。
+
+## 内置模块清单
+
+| 模块 ID | 说明 | 组成 |
+| --- | --- | --- |
+| `JobInformation` | 工单 / 载具 / 工序信息面板 | FastAPI 后端 + Vue 前端；内置 `header`、`inputCarriers`、`outputCarriers`、`timeline`、`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`。
+
+## 常用命令
+
+- `npx create-aiaui-module@latest --list` — 查看模板
+- `npx create-aiaui-module@latest <ModuleId>` — 生成（`--instance-root` 指定根目录）
+- `npx create-aiaui-module@latest --json --list` — 机器可读
+
+## 维护者（发布新模板）
+
+- 新增模块：在 `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

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createModule,
+  GeneratorError,
+  listTemplates,
+} 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 = {
+    json: false,
+    list: false,
+    instanceRoot: process.cwd(),
+    templateId: null,
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") options.json = true;
+    else if (arg === "--list") options.list = true;
+    else if (arg === "--instance-root" && args[index + 1])
+      options.instanceRoot = args[++index];
+    else if (!arg.startsWith("-") && options.templateId === null)
+      options.templateId = arg;
+    else
+      throw new GeneratorError(
+        "invalid_arguments",
+        `Unexpected argument: ${arg}`,
+      );
+  }
+  if (!options.list && !options.templateId) {
+    throw new GeneratorError(
+      "invalid_arguments",
+      "Usage: create-aiaui-module <ModuleId> [--instance-root <path>] [--json]",
+    );
+  }
+  return options;
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  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 =
+    error instanceof GeneratorError ? error.code : "generator_failed";
+  console.error(JSON.stringify({ code, message: error.message }));
+  process.exitCode = code === "module_exists" ? 3 : 2;
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "create-aiaui-module",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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"
+  },
+  "scripts": {
+    "test": "node tests/generator.test.js",
+    "verify-dist": "node scripts/verify-dist.mjs",
+    "prepack": "npm run verify-dist"
+  }
+}

package/runtime/__init__.py

@@ -0,0 +1,82 @@
+"""Instance-side entry point for enabled AIAUI modules.
+
+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
+
+
+class AIAUI:
+    """Host handle for one Instance's enabled AIAUI modules.
+
+    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.
+    """
+
+    _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/runtime/_runtime/__init__.py

@@ -0,0 +1,40 @@
+"""Inlined AIAUI module host runtime for generated Instances.
+
+Call attach() from the generated PyAIAUI entry point. This package is copied
+verbatim into ``PyAIAUI/_runtime`` by the module generator so Instances do not
+need an external ``aiaui`` dependency.
+"""
+
+import threading
+from pathlib import Path
+
+from .registry import discover
+
+__all__ = ["attach", "discover"]
+
+_hosts = {}
+_hosts_lock = threading.RLock()
+
+
+def attach(instance_root, *, services=None, logger=None):
+    """Load every enabled module under PyAIAUI/ and serve them on the fixed proxy port.
+
+    Returns the running ProxyHost, or None when no modules are enabled.
+    Call host.close() during Instance shutdown.
+    """
+    from .host import ProxyHost
+    from .loader import ModuleContext
+
+    root = Path(instance_root).resolve()
+    with _hosts_lock:
+        existing = _hosts.get(root)
+        if existing is not None and not existing.closed:
+            return existing
+        _hosts.pop(root, None)
+        port, modules = discover(root)
+        if not modules:
+            return None
+        context = ModuleContext(root, services or {}, logger)
+        host = ProxyHost(root, port, modules, context)
+        _hosts[root] = host
+        return host

package/runtime/_runtime/host.py

@@ -0,0 +1,88 @@
+"""One loopback HTTP host per Instance; every enabled module mounts its own router here."""
+
+import threading
+import time
+from pathlib import Path
+
+from .loader import load_api
+from .registry import ModuleDescriptor
+
+OWNER = "aiaui-proxy"
+
+
+class ProxyHost:
+    def __init__(self, instance_root: Path, port: int, modules: list[ModuleDescriptor], context):
+        import fcntl
+        import os
+
+        import uvicorn
+        from fastapi import FastAPI
+
+        self.root = Path(instance_root)
+        self.port = port
+        self.modules = modules
+        self.closed = False
+        self.thread: threading.Thread | None = None
+
+        config_dir = self.root / "Config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        lock_path = config_dir / ".aiaui.host.lock"
+        descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+        self._lock_file = os.fdopen(descriptor, "a")
+        try:
+            fcntl.flock(self._lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            self._lock_file.close()
+            raise ValueError("Another process already hosts this Instance") from error
+
+        self._app = FastAPI(title=f"AIAUI modules for {self.root.name}")
+        for module in modules:
+            router = load_api(module, context)
+            self._app.include_router(router, prefix=f"/modules/{module.id}")
+        self._app.add_api_route(
+            "/modules",
+            lambda: {"modules": [m.id for m in modules]},
+            methods=["GET"],
+            include_in_schema=False,
+        )
+
+        self.server = uvicorn.Server(uvicorn.Config(self._app, host="127.0.0.1", port=port))
+        # Do not use uvicorn.Server.run(). In some Instance environments asyncio.run
+        # is replaced (for example by nest_asyncio) with a wrapper that does not
+        # accept ``loop_factory``, which uvicorn 0.54+ passes through. Running the
+        # coroutine on an event loop we own keeps this runtime self-contained.
+        self.thread = threading.Thread(target=self._serve, daemon=True, name="aiaui-proxy")
+        self.thread.start()
+
+        deadline_limit = 100
+        while not self.server.started and deadline_limit > 0:
+            if not self.thread.is_alive():
+                self.close()
+                raise RuntimeError("AIAUI proxy host failed to start")
+            time.sleep(0.05)
+            deadline_limit -= 1
+        if not self.server.started:
+            self.close()
+            raise RuntimeError("AIAUI proxy host did not become ready")
+        self.port = self.server.servers[0].sockets[0].getsockname()[1]
+
+    def _serve(self):
+        import asyncio
+
+        # Create a fresh loop for this thread instead of relying on the process
+        # global ``asyncio.run`` (it may have been patched by the Instance).
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            loop.run_until_complete(self.server.serve())
+        finally:
+            loop.close()
+
+    def close(self):
+        if self.closed:
+            return
+        self.closed = True
+        if self.thread is not None:
+            self.server.should_exit = True
+            self.thread.join(timeout=5)
+        self._lock_file.close()

package/runtime/_runtime/loader.py

@@ -0,0 +1,39 @@
+"""Import a module api.py and call its create_api(context) factory. Nothing else is interpreted."""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+from .registry import ModuleDescriptor
+
+
+class ModuleContext:
+    """Everything the platform hands to a module backend."""
+
+    def __init__(self, instance_root, services, logger=None):
+        self.instance_root = Path(instance_root)
+        self.services = dict(services or {})
+        self.logger = logger
+        self.directory = instance_root / "PyAIAUI" if False else None
+
+    @property
+    def resources(self) -> Path:
+        return self.instance_root / "PyAIAUI"
+
+
+def load_api(module: ModuleDescriptor, context: ModuleContext):
+    module_name = f"aiaui_module_{module.id}".replace("-", "_")
+    spec = importlib.util.spec_from_file_location(module_name, module.api_file)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"Cannot import {module.api_file}")
+    module_object = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module_object
+    try:
+        spec.loader.exec_module(module_object)
+    except Exception:
+        sys.modules.pop(module_name, None)
+        raise
+    factory = getattr(module_object, "create_api", None)
+    if factory is None:
+        raise ValueError(f"{module.api_file} must define create_api(context)")
+    return factory(context)

package/runtime/_runtime/registry.py

@@ -0,0 +1,93 @@
+"""Discover modules exclusively from an Instance's AIAUIProtocol contract."""
+
+import json
+import re
+from pathlib import Path
+
+PROTOCOL_NAME = "AIAUIProtocol.json"
+MODULE_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_]*")
+
+
+class ProtocolError(ValueError):
+    pass
+
+
+class ModuleDescriptor:
+    """What the platform needs to know about one module, derived purely by convention."""
+
+    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"
+
+    @property
+    def has_backend(self) -> bool:
+        return self.api_file.is_file()
+
+    @property
+    def has_frontend(self) -> bool:
+        return self.frontend_entry.is_dir() and any(self.frontend_entry.glob("*.js"))
+
+    @property
+    def frontend_manifest(self) -> Path:
+        return self.frontend_entry / "manifest.json"
+
+
+def read_protocol(instance_root: Path) -> dict | None:
+    """Read the new protocol; a null port is valid while all modules are disabled."""
+
+    path = Path(instance_root) / "Config" / PROTOCOL_NAME
+    if path.is_symlink():
+        raise ProtocolError(PROTOCOL_NAME + " must be a real file")
+    if not path.exists():
+        return None
+    if not path.is_file():
+        raise ProtocolError(PROTOCOL_NAME + " must be a real file")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as cause:
+        raise ProtocolError(PROTOCOL_NAME + " is missing or invalid") from cause
+    if not isinstance(data, dict) or data.get("schemaVersion") != 1:
+        raise ProtocolError(PROTOCOL_NAME + " requires schemaVersion 1")
+    port = data.get("port")
+    if port is not None and (
+        not isinstance(port, int) or isinstance(port, bool) or not 1 <= port <= 65535
+    ):
+        raise ProtocolError(PROTOCOL_NAME + " port must be null or a valid integer")
+    modules = data.get("modules")
+    if not isinstance(modules, list):
+        raise ProtocolError(PROTOCOL_NAME + " modules must be an array")
+    names = set()
+    for entry in modules:
+        if (
+            not isinstance(entry, dict)
+            or not isinstance(entry.get("name"), str)
+            or not MODULE_NAME.fullmatch(entry["name"])
+            or not isinstance(entry.get("enabled"), bool)
+            or entry["name"] in names
+        ):
+            raise ProtocolError(PROTOCOL_NAME + " contains an invalid or duplicate module")
+        names.add(entry["name"])
+    return data
+
+
+def discover(instance_root: Path) -> tuple[int, list[ModuleDescriptor]]:
+    """Return the Instance proxy port and enabled modules from AIAUIProtocol."""
+
+    root = Path(instance_root)
+    modules_root = root / "PyAIAUI"
+    protocol = read_protocol(root)
+    if protocol is None:
+        return 0, []
+    names = sorted(entry["name"] for entry in protocol["modules"] if entry["enabled"])
+    port = protocol["port"]
+    if names and port is None:
+        raise ProtocolError(PROTOCOL_NAME + " needs a port before enabling modules")
+    descriptors = []
+    for name in names:
+        directory = modules_root / name
+        if not directory.is_dir() or directory.is_symlink():
+            raise ProtocolError("PyAIAUI/" + name + " is missing")
+        descriptors.append(ModuleDescriptor(name, directory))
+    return port or 0, descriptors

package/src/errors.js

@@ -0,0 +1,6 @@
+export class GeneratorError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}