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

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}`,
+    );
+  }
+}

package/src/protocol.js

@@ -0,0 +1,98 @@
+import { lstat, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { GeneratorError } from "./errors.js";
+
+const MODULE_ID = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function validProtocol(value) {
+  return (
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    value.schemaVersion === 1 &&
+    (value.port === null ||
+      (Number.isInteger(value.port) &&
+        value.port >= 1 &&
+        value.port <= 65535)) &&
+    Array.isArray(value.modules) &&
+    value.modules.every(
+      (module) =>
+        module &&
+        typeof module === "object" &&
+        MODULE_ID.test(module.name) &&
+        typeof module.enabled === "boolean",
+    ) &&
+    new Set(value.modules.map((module) => module.name)).size ===
+      value.modules.length
+  );
+}
+
+export async function registerModule(instanceRoot, moduleId) {
+  const configPath = path.join(instanceRoot, "Config", "AIAUIProtocol.json");
+  const draft = {
+    schemaVersion: 1,
+    port: null,
+    modules: [{ name: moduleId, enabled: false }],
+  };
+  let entry;
+  try {
+    entry = await lstat(configPath);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (!entry) {
+    try {
+      const handle = await open(configPath, "wx");
+      try {
+        await handle.writeFile(JSON.stringify(draft, null, 2) + "\n");
+      } catch (error) {
+        await handle.close();
+        await rm(configPath, { force: true });
+        throw error;
+      }
+      await handle.close();
+      return { configPath, enabled: false, port: null };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      entry = await lstat(configPath);
+    }
+  }
+  if (!entry.isFile() || entry.isSymbolicLink()) {
+    throw new GeneratorError(
+      "invalid_protocol",
+      "AIAUIProtocol.json must be a real file",
+    );
+  }
+  let protocol;
+  try {
+    protocol = JSON.parse(await readFile(configPath, "utf8"));
+  } catch (error) {
+    throw new GeneratorError(
+      "invalid_protocol",
+      `AIAUIProtocol.json is not valid JSON: ${error.message}`,
+    );
+  }
+  if (!validProtocol(protocol)) {
+    throw new GeneratorError(
+      "invalid_protocol",
+      "AIAUIProtocol.json must have schemaVersion 1, a port or null, and a modules array",
+    );
+  }
+  const existing = protocol.modules.find((module) => module.name === moduleId);
+  if (existing)
+    return { configPath, enabled: existing.enabled, port: protocol.port };
+  protocol.modules.push({ name: moduleId, enabled: false });
+  const temporary = `${configPath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(protocol, null, 2) + "\n", {
+      flag: "wx",
+      mode: entry.mode,
+    });
+    await rename(temporary, configPath);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return { configPath, enabled: false, port: protocol.port };
+}

package/templates/HelloWorld/README.md

@@ -0,0 +1,13 @@
+# HelloWorld module
+
+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:
+
+```python
+from PyAIAUI import AIAUI
+
+aiaui = AIAUI.start(services={...})
+# ... later ...
+aiaui.stop()
+```

package/templates/HelloWorld/contractVersion

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

package/templates/HelloWorld/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/HelloWorld/resources/dist/manifest.json

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