create-aiaui-module 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# AIAUI module templates
 
-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.
+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/`.
+
+## Use with npx (no global install)
+
+From an Instance root containing `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.
+
+## Local use
+
+From an Instance root in a checkout:
+
+```bash
+node /path/to/ServerManageForLiunx/UIModulesTemplate/bin/create-aiaui-module.js --list
+node /path/to/ServerManageForLiunx/UIModulesTemplate/bin/create-aiaui-module.js JobInformation
+```
+
+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.
+
+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`).
+
+## 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.

package/bin/create-aiaui-module.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+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)));
+
+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));
+  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.",
+    );
+  }
+} 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,15 @@
 {
   "name": "create-aiaui-module",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Scaffold AIAUI Instance modules (FastAPI router + editable Vue frontend) via npx",
+  "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,39 @@
+"""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).
+"""
+
+from pathlib import Path
+
+from ._runtime import attach
+
+_host = None
+
+
+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``.
+    """
+    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()

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;
+  }
+}

package/src/generator.js

@@ -0,0 +1,194 @@
+import { constants } from "node:fs";
+import {
+  access,
+  copyFile,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+} from "node:fs/promises";
+import path from "node:path";
+
+import { GeneratorError } from "./errors.js";
+import { registerModule } from "./protocol.js";
+
+export { GeneratorError } from "./errors.js";
+
+const MODULE_ID = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+async function realDirectory(directory) {
+  try {
+    const entry = await lstat(directory);
+    return entry.isDirectory() && !entry.isSymbolicLink();
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function templateInfo(root, id) {
+  if (!MODULE_ID.test(id)) return null;
+  const directory = path.join(root, "templates", id);
+  if (!(await realDirectory(directory))) return null;
+  try {
+    const contractVersion = (
+      await readFile(path.join(directory, "contractVersion"), "utf8")
+    ).trim();
+    if (!/^\d+$/.test(contractVersion)) return null;
+    return { id, contractVersion, directory };
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function listTemplates(root) {
+  let entries;
+  try {
+    entries = await readdir(path.join(root, "templates"), {
+      withFileTypes: true,
+    });
+  } catch (error) {
+    if (error.code === "ENOENT")
+      throw new GeneratorError(
+        "package_missing",
+        "Template package is missing",
+      );
+    throw error;
+  }
+  const templates = await Promise.all(
+    entries.map((entry) => templateInfo(root, entry.name)),
+  );
+  return templates
+    .filter(Boolean)
+    .map(({ id, contractVersion }) => ({ id, contractVersion }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+async function copyTree(source, target) {
+  let filesCopied = 0;
+  for (const entry of (await readdir(source, { withFileTypes: true })).sort(
+    (a, b) => a.name.localeCompare(b.name),
+  )) {
+    if (
+      ["__pycache__", "node_modules", ".git", ".DS_Store"].includes(
+        entry.name,
+      ) ||
+      /\.py[co]$/.test(entry.name)
+    )
+      continue;
+    const from = path.join(source, entry.name);
+    const to = path.join(target, entry.name);
+    if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
+      throw new GeneratorError(
+        "invalid_template",
+        `Template contains an unsafe member: ${entry.name}`,
+      );
+    }
+    if (entry.isDirectory()) {
+      await mkdir(to);
+      filesCopied += await copyTree(from, to);
+    } else {
+      await copyFile(from, to, constants.COPYFILE_EXCL);
+      filesCopied += 1;
+    }
+  }
+  return filesCopied;
+}
+
+export async function createModule({ templateId, instanceRoot, root }) {
+  const template = await templateInfo(root, templateId);
+  if (!template)
+    throw new GeneratorError(
+      "unknown_template",
+      `Unknown template: ${templateId}`,
+    );
+  const instance = path.resolve(instanceRoot);
+  if (
+    !(await realDirectory(instance)) ||
+    !(await realDirectory(path.join(instance, "Config")))
+  ) {
+    throw new GeneratorError(
+      "invalid_instance",
+      "Instance root must contain a real Config directory",
+    );
+  }
+  const modules = path.join(instance, "PyAIAUI");
+  if (!(await realDirectory(modules))) {
+    try {
+      await mkdir(modules);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new GeneratorError(
+          "invalid_instance",
+          "PyAIAUI must be a real directory",
+        );
+      }
+      throw new GeneratorError(
+        "copy_failed",
+        `Could not create PyAIAUI: ${error.message}`,
+      );
+    }
+  }
+  try {
+    await access(modules, constants.W_OK);
+  } catch {
+    throw new GeneratorError("invalid_instance", "PyAIAUI is not writable");
+  }
+  const target = path.join(modules, templateId);
+  try {
+    await mkdir(target);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new GeneratorError("module_exists", `${target} already exists`);
+    throw new GeneratorError(
+      "copy_failed",
+      `Could not create module directory: ${error.message}`,
+    );
+  }
+  const bootstrap = path.join(modules, "__init__.py");
+  let createdBootstrap = false;
+  let createdRuntime = false;
+  try {
+    const filesCopied = await copyTree(template.directory, target);
+    const runtimeSource = path.join(root, "runtime", "_runtime");
+    if (await realDirectory(runtimeSource)) {
+      const runtimeTarget = path.join(modules, "_runtime");
+      if (!(await realDirectory(runtimeTarget))) {
+        await mkdir(runtimeTarget);
+        await copyTree(runtimeSource, runtimeTarget);
+        createdRuntime = true;
+      }
+    }
+    const bootstrapSource = path.join(root, "runtime", "__init__.py");
+    try {
+      await copyFile(bootstrapSource, bootstrap, constants.COPYFILE_EXCL);
+      createdBootstrap = true;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const existing = await lstat(bootstrap);
+      if (!existing.isFile() || existing.isSymbolicLink()) {
+        throw new GeneratorError(
+          "invalid_instance",
+          "PyAIAUI/__init__.py must be a real file",
+        );
+      }
+    }
+    const registration = await registerModule(instance, templateId);
+    return { moduleId: templateId, path: target, filesCopied, ...registration };
+  } catch (error) {
+    await rm(target, { recursive: true, force: true });
+    if (createdBootstrap) await rm(bootstrap, { force: true });
+    if (createdRuntime)
+      await rm(path.join(modules, "_runtime"), {
+        recursive: true,
+        force: true,
+      });
+    if (error instanceof GeneratorError) throw error;
+    throw new GeneratorError(
+      "copy_failed",
+      `Could not copy template: ${error.message}`,
+    );
+  }
+}