@jskit-ai/ui-generator 0.1.3

package/src/server/subcommands/support.js

@@ -0,0 +1,165 @@
+import path from "node:path";
+import {
+  resolveRequiredAppRoot,
+  toPosixPath
+} from "@jskit-ai/kernel/server/support";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { toCamelCase, toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
+
+const DEFAULT_COMPONENT_DIRECTORY = "src/components";
+const MAIN_CLIENT_PROVIDER_FILE = "packages/main/src/client/providers/MainClientProvider.js";
+const PLACEMENT_FILE = "src/placement.js";
+
+function toKebabCase(value = "") {
+  return toSnakeCase(value).replaceAll("_", "-");
+}
+
+function toPascalCase(value = "") {
+  const camel = toCamelCase(toSnakeCase(value));
+  if (!camel) {
+    return "";
+  }
+
+  return `${camel.slice(0, 1).toUpperCase()}${camel.slice(1)}`;
+}
+
+function requireOption(options = {}, optionName = "", { context = "ui-generator" } = {}) {
+  const optionValue = normalizeText(options?.[optionName]);
+  if (!optionValue) {
+    throw new Error(`${context} requires --${optionName}.`);
+  }
+
+  return optionValue;
+}
+
+function resolvePathWithinApp(appRoot, targetPath, { context = "ui-generator" } = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context
+  });
+
+  const normalizedTargetPath = normalizeText(targetPath);
+  if (!normalizedTargetPath) {
+    throw new Error(`${context} requires target path.`);
+  }
+
+  const absolutePath = path.resolve(resolvedAppRoot, normalizedTargetPath);
+  const relativePath = path.relative(resolvedAppRoot, absolutePath);
+  if (
+    !relativePath ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  ) {
+    throw new Error(`${context} target path must stay within app root: ${normalizedTargetPath}`);
+  }
+
+  return Object.freeze({
+    absolutePath,
+    relativePath: toPosixPath(relativePath)
+  });
+}
+
+function ensureTrailingNewline(value = "") {
+  const source = String(value || "");
+  return source.endsWith("\n") ? source : `${source}\n`;
+}
+
+function appendBlockIfMarkerMissing(source = "", marker = "", block = "") {
+  const normalizedMarker = String(marker || "").trim();
+  const normalizedBlock = String(block || "").trim();
+  const sourceText = String(source || "");
+  if (!normalizedMarker || !normalizedBlock || sourceText.includes(normalizedMarker)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  return {
+    changed: true,
+    content: `${ensureTrailingNewline(sourceText)}${normalizedBlock}\n`
+  };
+}
+
+function insertImportIfMissing(source = "", importLine = "") {
+  const normalizedImportLine = String(importLine || "").trim();
+  if (!normalizedImportLine) {
+    return {
+      changed: false,
+      content: String(source || "")
+    };
+  }
+
+  const sourceText = String(source || "");
+  if (sourceText.includes(normalizedImportLine)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const importPattern = /^import\s+[^;]+;\s*$/gm;
+  let match = null;
+  let insertionIndex = 0;
+  while ((match = importPattern.exec(sourceText)) !== null) {
+    insertionIndex = match.index + match[0].length;
+  }
+
+  if (insertionIndex > 0) {
+    return {
+      changed: true,
+      content: `${sourceText.slice(0, insertionIndex)}\n${normalizedImportLine}${sourceText.slice(insertionIndex)}`
+    };
+  }
+
+  return {
+    changed: true,
+    content: `${normalizedImportLine}\n${sourceText}`
+  };
+}
+
+function insertBeforeClassDeclaration(source = "", line = "", { className = "", contextFile = "" } = {}) {
+  const normalizedLine = String(line || "").trim();
+  if (!normalizedLine) {
+    return {
+      changed: false,
+      content: String(source || "")
+    };
+  }
+
+  const sourceText = String(source || "");
+  if (sourceText.includes(normalizedLine)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const normalizedClassName = String(className || "").trim();
+  const classPattern = new RegExp(`^class\\s+${normalizedClassName}\\b`, "m");
+  const classMatch = classPattern.exec(sourceText);
+  if (!classMatch) {
+    const targetFile = String(contextFile || "").trim() || "target file";
+    throw new Error(`ui-generator could not find ${normalizedClassName} class declaration in ${targetFile}.`);
+  }
+
+  const insertionIndex = classMatch.index;
+  return {
+    changed: true,
+    content: `${sourceText.slice(0, insertionIndex)}${normalizedLine}\n\n${sourceText.slice(insertionIndex)}`
+  };
+}
+
+export {
+  DEFAULT_COMPONENT_DIRECTORY,
+  MAIN_CLIENT_PROVIDER_FILE,
+  PLACEMENT_FILE,
+  toKebabCase,
+  toPascalCase,
+  requireOption,
+  resolvePathWithinApp,
+  ensureTrailingNewline,
+  appendBlockIfMarkerMissing,
+  insertImportIfMissing,
+  insertBeforeClassDeclaration
+};

package/templates/src/pages/admin/ui-generator/Page.vue

@@ -0,0 +1,6 @@
+<template>
+  <section class="pa-4">
+    <h1 class="text-h5 mb-2">${option:name|trim}</h1>
+    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your page implementation.</p>
+  </section>
+</template>

package/test/buildTemplateContext.test.js

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { buildUiPageTemplateContext } from "../src/server/buildTemplateContext.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeVueFile(appRoot, relativePath, source = "") {
+  const absoluteFile = path.join(appRoot, relativePath);
+  await mkdir(path.dirname(absoluteFile), { recursive: true });
+  await writeFile(
+    absoluteFile,
+    source ||
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+  </div>
+</template>
+`,
+    "utf8"
+  );
+}
+
+test("buildUiPageTemplateContext resolves placement from default app ShellOutlet target", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeVueFile(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet host="shell-layout" position="primary-menu" />
+  </div>
+</template>
+`
+    );
+    await writeVueFile(
+      appRoot,
+      "src/pages/admin/workspace/settings/index.vue",
+      `<template>
+  <section>
+    <ShellOutlet host="workspace-settings" position="forms" default />
+  </section>
+</template>
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      options: {}
+    });
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "workspace-settings");
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "forms");
+  });
+});
+
+test("buildUiPageTemplateContext supports explicit placement override", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      options: {
+        placement: "shell-layout:top-right"
+      }
+    });
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "top-right");
+  });
+});
+
+test("buildUiPageTemplateContext supports explicit package outlet placement", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+    await writeVueFile(
+      appRoot,
+      ".jskit/lock.json",
+      `${JSON.stringify(
+        {
+          lockVersion: 1,
+          installedPackages: {
+            "@example/users-web": {
+              packageId: "@example/users-web",
+              source: {
+                type: "npm-installed-package",
+                descriptorPath: "node_modules/@example/users-web/package.descriptor.mjs"
+              }
+            }
+          }
+        },
+        null,
+        2
+      )}\n`
+    );
+    await writeVueFile(
+      appRoot,
+      "node_modules/@example/users-web/package.descriptor.mjs",
+      `export default {
+  packageId: "@example/users-web",
+  metadata: {
+    ui: {
+      placements: {
+        outlets: [
+          { host: "workspace-tools", position: "primary-menu", source: "src/client/components/UsersWorkspaceToolsWidget.vue" }
+        ]
+      }
+    }
+  }
+};
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      options: {
+        placement: "workspace-tools:primary-menu"
+      }
+    });
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "workspace-tools");
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "primary-menu");
+  });
+});
+
+test("buildUiPageTemplateContext validates placement format", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+
+    await assert.rejects(
+      () =>
+        buildUiPageTemplateContext({
+          appRoot,
+          options: {
+            placement: "invalid-placement"
+          }
+        }),
+      /option "placement" must be in "host:position" format/
+    );
+  });
+});

package/test/containerSubcommand.test.js

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { runGeneratorSubcommand } from "../src/server/subcommands/container.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-container-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeAppFixture(appRoot) {
+  await mkdir(path.join(appRoot, "config"), { recursive: true });
+  await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
+  await mkdir(path.join(appRoot, "src"), { recursive: true });
+  await mkdir(path.join(appRoot, "packages", "main", "src", "client", "providers"), { recursive: true });
+
+  await writeFile(
+    path.join(appRoot, "config", "public.js"),
+    `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "", enabled: true, requiresAuth: false, requiresWorkspace: false },
+    admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true, requiresAuth: true, requiresWorkspace: true }
+  }
+};
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "src", "components", "ShellLayout.vue"),
+    `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet host="shell-layout" position="top-right" />
+  </div>
+</template>
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "src", "placement.js"),
+    `function addPlacement() {}
+
+export { addPlacement };
+export default function getPlacements() {
+  return [];
+}
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js"),
+    `const mainClientComponents = [];
+
+function registerMainClientComponent(componentToken, resolveComponent) {
+  const token = String(componentToken || "").trim();
+  if (!token || typeof resolveComponent !== "function") {
+    return;
+  }
+  mainClientComponents.push(
+    Object.freeze({
+      token,
+      resolveComponent
+    })
+  );
+}
+
+class MainClientProvider {}
+
+export { MainClientProvider, registerMainClientComponent };
+`,
+    "utf8"
+  );
+}
+
+test("ui-generator container subcommand creates parent route container with ShellOutlet and RouterView", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "container",
+      options: {
+        name: "Practice",
+        surface: "admin"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [
+      "packages/main/src/client/providers/MainClientProvider.js",
+      "src/components/SectionContainerShell.vue",
+      "src/components/SectionShellTabLinkItem.vue",
+      "src/pages/w/[workspaceSlug]/admin/practice.vue",
+      "src/placement.js"
+    ]);
+
+    const containerSource = await readFile(
+      path.join(appRoot, "src", "pages", "w", "[workspaceSlug]", "admin", "practice.vue"),
+      "utf8"
+    );
+    assert.match(containerSource, /<SectionContainerShell/);
+    assert.match(containerSource, /host="practice"/);
+    assert.match(containerSource, /<RouterView \/>/);
+    assert.match(containerSource, /"surface": "admin"/);
+
+    const sectionShellSource = await readFile(path.join(appRoot, "src", "components", "SectionContainerShell.vue"), "utf8");
+    assert.match(sectionShellSource, /<ShellOutlet :host="props\.host" :position="props\.position" \/>/);
+
+    const tabLinkSource = await readFile(path.join(appRoot, "src", "components", "SectionShellTabLinkItem.vue"), "utf8");
+    assert.match(tabLinkSource, /useWorkspaceRouteContext/);
+    assert.match(tabLinkSource, /class="section-shell-tab-link text-none"/);
+
+    const providerSource = await readFile(
+      path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js"),
+      "utf8"
+    );
+    assert.match(
+      providerSource,
+      /registerMainClientComponent\("local\.main\.ui\.section-shell\.tab-link-item", \(\) => SectionShellTabLinkItem\);/
+    );
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /id: "ui-generator\.container\.practice\.menu"/);
+    assert.match(placementSource, /host: "shell-layout"/);
+    assert.match(placementSource, /position: "primary-menu"/);
+    assert.match(placementSource, /workspaceSuffix: "\/practice"/);
+  });
+});

package/test/elementSubcommand.test.js

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { runGeneratorSubcommand } from "../src/server/subcommands/element.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-element-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeAppFixture(appRoot) {
+  await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
+  await mkdir(path.join(appRoot, "src", "pages", "admin", "workspace", "settings"), { recursive: true });
+  await mkdir(path.join(appRoot, "packages", "main", "src", "client", "providers"), { recursive: true });
+
+  await writeFile(
+    path.join(appRoot, "src", "components", "ShellLayout.vue"),
+    `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet host="shell-layout" position="top-right" />
+  </div>
+</template>
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "src", "pages", "admin", "workspace", "settings", "index.vue"),
+    `<template>
+  <section>
+    <ShellOutlet host="workspace-settings" position="forms" />
+  </section>
+</template>
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "src", "placement.js"),
+    `function addPlacement() {}
+
+export { addPlacement };
+export default function getPlacements() {
+  return [];
+}
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js"),
+    `const mainClientComponents = [];
+
+function registerMainClientComponent(componentToken, resolveComponent) {
+  const token = String(componentToken || "").trim();
+  if (!token || typeof resolveComponent !== "function") {
+    return;
+  }
+  mainClientComponents.push(
+    Object.freeze({
+      token,
+      resolveComponent
+    })
+  );
+}
+
+class MainClientProvider {}
+
+export { MainClientProvider, registerMainClientComponent };
+`,
+    "utf8"
+  );
+}
+
+test("ui-generator element subcommand creates component and outlet placement", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "element",
+      options: {
+        name: "Ops Panel",
+        surface: "admin",
+        placement: "workspace-settings:forms"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [
+      "packages/main/src/client/providers/MainClientProvider.js",
+      "src/components/OpsPanelElement.vue",
+      "src/placement.js"
+    ]);
+
+    const providerSource = await readFile(
+      path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js"),
+      "utf8"
+    );
+    assert.match(providerSource, /import OpsPanelElement from "\/src\/components\/OpsPanelElement\.vue";/);
+    assert.match(providerSource, /registerMainClientComponent\("local\.main\.ui\.element\.ops-panel", \(\) => OpsPanelElement\);/);
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /id: "ui-generator\.element\.ops-panel"/);
+    assert.match(placementSource, /host: "workspace-settings"/);
+    assert.match(placementSource, /position: "forms"/);
+    assert.match(placementSource, /componentToken: "local\.main\.ui\.element\.ops-panel"/);
+  });
+});
+
+test("ui-generator element subcommand requires appRoot", async () => {
+  await assert.rejects(
+    () =>
+      runGeneratorSubcommand({
+        appRoot: "",
+        subcommand: "element",
+        options: {
+          name: "Ops Panel",
+          surface: "admin"
+        }
+      }),
+    /requires appRoot/
+  );
+});