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

package/templates/HelloWorld/resources/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "aiaui-hello-world-template",
+  "private": true,
+  "type": "module",
+  "scripts": { "build": "node build.mjs" },
+  "dependencies": { "vue": "^3.5.0" },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.0.0"
+  }
+}

package/templates/HelloWorld/resources/src/Hello.ce.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+defineProps<{ instanceId: string }>();
+</script>
+
+<template>
+  <section>
+    <h2>Hello from this Instance</h2>
+    <p>Instance: {{ instanceId }}</p>
+  </section>
+</template>
+
+<style>
+:host {
+  display: block;
+  color: var(--aia-text, #222);
+  font: inherit;
+}
+section {
+  padding: 16px;
+}
+h2 {
+  margin: 0 0 12px;
+  font-size: 1.25rem;
+}
+</style>

package/templates/HelloWorld/resources/src/index.ts

@@ -0,0 +1,32 @@
+import { defineCustomElement } from "vue";
+import Hello from "./Hello.ce.vue";
+
+type ModuleContext = {
+  instanceId: string;
+  place(spec: {
+    kind: "route";
+    path: string;
+    label: string;
+    order: number;
+  }): void;
+};
+
+const tagName = "aiaui-hello-world-panel";
+let mountedContainer: HTMLElement | null = null;
+
+export function mount(container: HTMLElement, context: ModuleContext) {
+  context.place({ kind: "route", path: "/hello", label: "Hello", order: 30 });
+  if (!customElements.get(tagName))
+    customElements.define(tagName, defineCustomElement(Hello));
+  const element = document.createElement(tagName) as HTMLElement & {
+    instanceId: string;
+  };
+  element.instanceId = context.instanceId;
+  container.replaceChildren(element);
+  mountedContainer = container;
+}
+
+export function unmount() {
+  mountedContainer?.replaceChildren();
+  mountedContainer = null;
+}

package/templates/HelloWorld/resources/vite.config.mjs

@@ -0,0 +1,13 @@
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+  plugins: [vue()],
+  // Browser builds must never reference Node's `process` global.
+  // Collapse Vue's process.env.NODE_ENV guards at build time.
+  define: { "process.env.NODE_ENV": JSON.stringify("production") },
+  build: {
+    emptyOutDir: true,
+    lib: { entry: "src/index.ts", formats: ["es"], fileName: "modules" },
+  },
+});

package/templates/JobInformation/CUSTOMIZATION.md

@@ -0,0 +1,173 @@
+# JobInformation customization
+
+This module ships with a built-in panel and exposes three customization
+levels. All of them keep the host-facing `mount(container, context)` /
+`unmount()` contract stable, so the Instance does not need to know which
+level you chose.
+
+## Customization entry
+
+Edit `resources/src/customization.ts`. It exports a single `customization`
+object:
+
+```ts
+import type { Customization } from "./contract";
+
+export const customization: Customization = { mode: "slots", slots: {} };
+```
+
+## Level 1 — default
+
+Leave `customization.ts` untouched. The module renders the built-in panel
+from `resources/src/defaults/`.
+
+## Level 2 — partial (replace boxes)
+
+Set `mode: "slots"` and provide a `slots` map. Keys are the built-in slot
+names; values are Vue components that receive `context` as a prop.
+
+```ts
+import MyHeader from "./custom/MyHeader.vue";
+import type { Customization } from "./contract";
+
+export const customization: Customization = {
+  mode: "slots",
+  slots: { header: MyHeader },
+};
+```
+
+### Built-in slots
+
+- `header` — job/lot identity and current state
+- `inputCarriers` — input carriers
+- `outputCarriers` — output carriers
+- `timeline` — progress steps
+- `recipe` — recipe/tool summary and actions
+
+### Slot component contract
+
+```vue
+<script setup lang="ts">
+import type { ModuleContext } from "../contract";
+
+defineProps<{ context: ModuleContext }>();
+</script>
+
+<template>
+  <section class="aiaji-slot">…</section>
+</template>
+```
+
+`context.api.call(method, path, options)` reaches this module's backend
+router. `context.signal` is aborted when the host unmounts the module, so
+long-running requests should observe it.
+
+
+## Communicating between slots
+
+Every slot component in one mount — built-in or custom — receives the same
+`context` object. On top of `api` and `signal`, `context` carries a **bus**
+created fresh on each `mount` and dead on `unmount` (so switching Instance
+gets you a clean bus automatically). It never crosses module or Instance
+boundaries.
+
+### 1. Events (recommended for most cases)
+
+Decoupled one-to-many communication:
+
+```ts
+// MyInput.vue — sender
+const props = defineProps<{ context: ModuleContext }>();
+
+function onSelect(id: string) {
+  props.context.bus.emit("lot:selected", { id });
+}
+
+onBeforeUnmount(() => props.context.bus.off("lot:selected", onSelect));
+```
+
+```ts
+// MyOutput.vue — receiver
+const props = defineProps<{ context: ModuleContext }>();
+
+onMounted(() =>
+  props.context.bus.on("lot:selected", (payload) => {
+    // `payload` is whatever the emitter passed; type it locally if you like
+    console.log("lot picked:", payload?.id);
+  }),
+);
+onBeforeUnmount(() => props.context.bus.off("lot:selected", someHandler));
+```
+
+- `emit` with no listeners is a no-op (safe).
+- Always `off` what you `on` in `onBeforeUnmount`, or old listeners fire on remount.
+- Type the payload where you need it; the bus signature is loose by design.
+
+### 2. Imperative handles (when you must call into a sibling)
+
+For `expose/peer` — e.g. OutputCarriers telling InputCarriers to focus a lot:
+
+```ts
+// MyInput.vue — publisher
+const handle = {
+  focusLot(id: string) {
+    /* imperative action inside InputCarriers */
+  },
+};
+onMounted(() => props.context.bus.expose("inputCarriers", handle));
+onUnmounted(() => props.context.bus.release("inputCarriers"));
+```
+
+```ts
+// MyOutput.vue — caller
+props.context.bus
+  .peer<{ focusLot(id: string): void }>("inputCarriers")
+  ?.focusLot("CR-01"); // always `?.` — peer returns undefined if the slot
+                        // was replaced away or hasn't mounted yet
+```
+
+### 3. Module-scope shared state (no bus needed)
+
+For pure data sync between two custom slots, a `reactive()` in a
+module-scope file also works with zero coupling:
+
+```ts
+// resources/src/custom/shared.ts
+import { reactive } from "vue";
+export const shared = reactive({ selectedLot: null as string | null });
+```
+
+```ts
+// both MyInput.vue and MyOutput.vue
+import { shared } from "./shared";
+shared.selectedLot = "CR-01"; // set in one, read in the other
+```
+
+Rule of thumb: defaults → events; only reach for `expose/peer` when the
+caller genuinely needs the peer's imperative API and accepts a
+not-yet-mounted/null risk.
+
+
+## Level 3 — full override
+
+Set `mode: "full"` and implement both entry points. The shell skips the
+built-in panel entirely.
+
+```ts
+export const customization: Customization = {
+  mode: "full",
+  mount(container, context) {
+    // render anything you want into `container`
+  },
+  unmount() {
+    // tear down your renderer
+  },
+};
+```
+
+## Styling
+
+The built-in styles are bundled into `modules.js`, so no separate CSS asset
+is required. Slot components can reuse the built-in `aiaji-*` classes and the
+`--aia-*` CSS variables (`--aia-text`, `--aia-border`, `--aia-accent`), or
+bring their own inline styles.

package/templates/JobInformation/README.md

@@ -0,0 +1,114 @@
+# JobInformation module
+
+This template scaffolds an editable "job information" UI module. The
+generator only produces scaffolding plus an inlined runtime
+(`PyAIAUI/_runtime`); **you do not need to install an `aiaui` package.**
+
+## Backend contract (what you implement)
+
+Implement one entry point in `api.py`:
+
+```python
+from fastapi import APIRouter
+
+
+def create_api(context) -> APIRouter:
+    router = APIRouter()
+    # reach Instance objects through context.services
+    return router
+```
+
+The generated host calls `create_api(context)` once and mounts the returned
+router at `/modules/JobInformation`. You receive:
+
+- `context.instance_root` — the Instance root directory.
+- `context.services` — a dict of the live objects your Instance passes in at
+  startup (see below).
+- `context.logger` — an optional logger, or `None`.
+
+Everything else about how to fetch or present data is yours to implement.
+
+## Frontend
+
+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.
+
+Slot components also communicate through `context.bus` (events or imperative handles); see CUSTOMIZATION.md for the patterns.
+
+Three levels are supported without changing `index.ts`:
+
+1. **Default** — do nothing; the built-in panel renders.
+2. **Partial** — replace one or more named boxes:
+
+   ```ts
+   // resources/src/customization.ts
+   import MyHeader from "./custom/MyHeader.vue";
+   import type { Customization } from "./contract";
+
+   export const customization: Customization = {
+     mode: "slots",
+     slots: { header: MyHeader },
+   };
+   ```
+
+3. **Full** — replace the whole module, including its page and data flow:
+
+   ```ts
+   export const customization: Customization = {
+     mode: "full",
+     mount(container, context) { /* your own renderer */ },
+     unmount() { /* your own teardown */ },
+   };
+   ```
+
+See `CUSTOMIZATION.md` for the slot names and component contract.
+
+Rebuild after editing:
+
+```bash
+cd resources
+npm install
+npm run build
+```
+
+For quick iteration, `npm run dev` runs `vite build --watch` and keeps
+`dist/manifest.json` valid on every rebuild.
+
+## Instance startup (wiring)
+
+Call the generated entry point from your Instance's own startup method:
+
+```python
+from PyAIAUI import AIAUI
+
+
+aiaui = AIAUI.start(services={
+    "secs_server": secs_server,
+    "job_repository": job_repository,
+})
+# aiaui is None when no modules are enabled
+
+# ... later, during shutdown ...
+aiaui.stop()
+```
+
+`start()` returns `None` when `JobInformation` is disabled in
+`Config/AIAUIProtocol.json`; otherwise it returns the running host.
+
+## Dependencies (reminder, not installed automatically)
+
+The backend example uses FastAPI and the generated host runs on Uvicorn.
+Install them into the Instance's own Python environment:
+
+```bash
+pip install fastapi uvicorn
+```
+
+Generation does not install dependencies or start any process. Set a free
+loopback port and enable the module in `Config/AIAUIProtocol.json` only after
+you have integrated `start()` / `stop()` into the Instance lifecycle.

package/templates/JobInformation/api.py

@@ -0,0 +1,53 @@
+"""Editable Job Information example, mounted under /modules/JobInformation."""
+
+import inspect
+
+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.AIAUI.start(services={...})``
+    and they arrive here through ``context.services``.
+    """
+    router = APIRouter()
+
+    @router.get("/server")
+    async def server():
+        secs_server = context.services.get("secs_server")
+        if secs_server is None:
+            return {"available": False, "name": None, "connected": None}
+        driver = getattr(secs_server, "driver", None)
+        check = getattr(driver, "is_connected", None)
+        connected = check() if callable(check) else None
+        if inspect.isawaitable(connected):
+            connected = await connected
+        return {
+            "available": True,
+            "name": getattr(secs_server, "name", None),
+            "connected": connected,
+        }
+
+    @router.get("/jobs")
+    async def jobs(name: str = "", page: int = 1, pageSize: int = 20):
+        repository = context.services.get("job_repository")
+        if repository is not None:
+            result = repository.list_jobs(name=name, page=page, page_size=pageSize)
+            return await result if inspect.isawaitable(result) else result
+
+        # Sample data is used only until the Instance injects a repository.
+        items = [
+            {"id": "demo-1", "name": "DEMO-JOB-001", "state": "Running"},
+            {"id": "demo-2", "name": "DEMO-JOB-002", "state": "Queued"},
+        ]
+        matched = [item for item in items if name.casefold() in item["name"].casefold()]
+        start = (page - 1) * pageSize
+        return {
+            "items": matched[start : start + pageSize],
+            "total": len(matched),
+            "page": page,
+            "pageSize": pageSize,
+        }
+
+    return router

package/templates/JobInformation/contractVersion

@@ -0,0 +1 @@
+1

package/templates/JobInformation/resources/build.mjs

@@ -0,0 +1,9 @@
+import { writeFile } from "node:fs/promises";
+import { build } from "vite";
+
+await build();
+await writeFile(
+  "dist/manifest.json",
+  JSON.stringify({ entry: "modules.js", files: ["modules.js"] }, null, 2) +
+    "\n",
+);

package/templates/JobInformation/resources/dist/manifest.json

@@ -0,0 +1,6 @@
+{
+  "entry": "modules.js",
+  "files": [
+    "modules.js"
+  ]
+}