@jskit-ai/ui-generator 0.1.14 → 0.1.15

package/test/outletSubcommand.test.js

@@ -14,7 +14,7 @@ async function withTempApp(run) {
   }
 }
 
-test("ui-generator outlet injects ShellOutlet and RouterView into existing page", async () => {
+test("ui-generator outlet injects a generic ShellOutlet into an existing page", async () => {
   await withTempApp(async (appRoot) => {
     const targetFile = "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue";
     const targetPath = path.join(appRoot, targetFile);
@@ -38,9 +38,9 @@ import { computed } from "vue";
     const result = await runGeneratorSubcommand({
       appRoot,
       subcommand: "outlet",
+      args: [targetFile],
       options: {
-        file: targetFile,
-        host: "contact-view"
+        target: "contact-view"
       }
     });
 
@@ -48,17 +48,16 @@ import { computed } from "vue";
 
     const output = await readFile(targetPath, "utf8");
     assert.match(output, /import ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/);
-    assert.match(output, /import \{ RouterView \} from "vue-router";/);
     assert.match(output, /<ShellOutlet host="contact-view" position="sub-pages" \/>/);
-    assert.equal((output.match(/<RouterView \/>/g) || []).length, 1);
+    assert.doesNotMatch(output, /RouterView/);
     assert.doesNotMatch(output, /jskit:ui-generator\.outlet:/);
 
     const rerun = await runGeneratorSubcommand({
       appRoot,
       subcommand: "outlet",
+      args: [targetFile],
       options: {
-        file: targetFile,
-        host: "contact-view"
+        target: "contact-view"
       }
     });
 
@@ -66,7 +65,7 @@ import { computed } from "vue";
   });
 });
 
-test("ui-generator outlet does not add second RouterView when one already exists", async () => {
+test("ui-generator outlet does not inject a second matching outlet", async () => {
   await withTempApp(async (appRoot) => {
     const targetFile = "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue";
     const targetPath = path.join(appRoot, targetFile);
@@ -75,12 +74,12 @@ test("ui-generator outlet does not add second RouterView when one already exists
     await writeFile(
       targetPath,
       `<script setup>
-import { RouterView } from "vue-router";
+import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
 </script>
 
 <template>
   <section>
-    <RouterView />
+    <ShellOutlet host="contact-view" position="sub-pages" />
   </section>
 </template>
 `,
@@ -90,20 +89,22 @@ import { RouterView } from "vue-router";
     await runGeneratorSubcommand({
       appRoot,
       subcommand: "outlet",
+      args: [targetFile],
       options: {
-        file: targetFile,
-        host: "contact-view"
+        target: "contact-view"
       }
     });
 
     const output = await readFile(targetPath, "utf8");
-    assert.match(output, /<ShellOutlet host="contact-view" position="sub-pages" \/>/);
-    assert.equal((output.match(/<RouterView \/>/g) || []).length, 1);
-    assert.equal((output.match(/import \{ RouterView \} from "vue-router";/g) || []).length, 1);
+    assert.equal((output.match(/<ShellOutlet host="contact-view" position="sub-pages" \/>/g) || []).length, 1);
+    assert.equal(
+      (output.match(/import ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/g) || []).length,
+      1
+    );
   });
 });
 
-test("ui-generator outlet-only mode injects only ShellOutlet and creates script setup when missing", async () => {
+test("ui-generator outlet creates script setup when missing", async () => {
   await withTempApp(async (appRoot) => {
     const targetFile = "src/components/ContactDetailsPanel.vue";
     const targetPath = path.join(appRoot, targetFile);
@@ -121,19 +122,16 @@ test("ui-generator outlet-only mode injects only ShellOutlet and creates script
     await runGeneratorSubcommand({
       appRoot,
       subcommand: "outlet",
+      args: [targetFile],
       options: {
-        file: targetFile,
-        host: "contact-view",
-        position: "sub-pages",
-        mode: "outlet-only"
+        target: "contact-view"
       }
     });
 
     const output = await readFile(targetPath, "utf8");
     assert.match(output, /<script setup>/);
     assert.match(output, /import ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/);
-    assert.doesNotMatch(output, /import \{ RouterView \} from "vue-router";/);
-    assert.doesNotMatch(output, /<RouterView \/>/);
+    assert.doesNotMatch(output, /RouterView/);
   });
 });
 
@@ -161,10 +159,9 @@ test("ui-generator outlet inserts generated script after existing route block",
     await runGeneratorSubcommand({
       appRoot,
       subcommand: "outlet",
+      args: [targetFile],
       options: {
-        file: targetFile,
-        host: "contact-view",
-        mode: "outlet-only"
+        target: "contact-view"
       }
     });
 
@@ -204,16 +201,82 @@ test("ui-generator outlet keeps indentation when injected into nested template b
     await runGeneratorSubcommand({
       appRoot,
       subcommand: "outlet",
+      args: [targetFile],
       options: {
-        file: targetFile,
-        host: "contact-view",
-        mode: "routed"
+        target: "contact-view"
       }
     });
 
     const output = await readFile(targetPath, "utf8");
-    assert.match(output, /\n\s{2}<\/section>\n\s{2}<ShellOutlet host="contact-view" position="sub-pages" \/>\n\s{2}<RouterView \/>\n<\/template>/);
+    assert.match(output, /\n\s{2}<\/section>\n\s{2}<ShellOutlet host="contact-view" position="sub-pages" \/>\n<\/template>/);
     assert.match(output, /<template v-else-if="view\.isLoading">\n\s*<v-skeleton-loader type="heading, text@2, article" \/>\n\s*<\/template>/);
     assert.doesNotMatch(output, /jskit:ui-generator\.outlet:/);
   });
 });
+
+test("ui-generator outlet rejects unsupported options", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/components/ContactDetailsPanel.vue";
+    const targetPath = path.join(appRoot, targetFile);
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, "<template><div /></template>\n", "utf8");
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "outlet",
+        args: [targetFile],
+        options: {
+          target: "contact-view",
+          bogus: "routed"
+        }
+      }),
+      /ui-generator outlet received unsupported option: --bogus\./
+    );
+  });
+});
+
+test("ui-generator outlet supports explicit target host:position", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/components/ContactDetailsPanel.vue";
+    const targetPath = path.join(appRoot, targetFile);
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, "<template><div /></template>\n", "utf8");
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "outlet",
+      args: [targetFile],
+      options: {
+        target: "customer-view:summary-actions"
+      }
+    });
+
+    const output = await readFile(targetPath, "utf8");
+    assert.match(output, /<ShellOutlet host="customer-view" position="summary-actions" \/>/);
+  });
+});
+
+test("ui-generator outlet validates target format", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/components/ContactDetailsPanel.vue";
+    const targetPath = path.join(appRoot, targetFile);
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, "<template><div /></template>\n", "utf8");
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "outlet",
+        args: [targetFile],
+        options: {
+          target: "customer-view:"
+        }
+      }),
+      /ui-generator outlet option "target" must be "host" or "host:position"\./
+    );
+  });
+});

package/test/packageDescriptor.test.js

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import descriptor from "../package.descriptor.mjs";
+
+test("ui-generator surface options validate against enabled surface ids", () => {
+  assert.equal(descriptor.kind, "generator");
+  assert.equal(descriptor.options?.surface?.validationType, "enabled-surface-id");
+  assert.equal(descriptor.metadata?.generatorSubcommands?.["placed-element"]?.optionNames?.includes("surface"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.page?.optionNames?.includes("force"), true);
+});

package/test/pageSubcommand.test.js

@@ -0,0 +1,352 @@
+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/page.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-page-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+function toPagePath(targetFile = "") {
+  return path.join("src/pages", targetFile);
+}
+
+async function writeAppFixture(appRoot, { configSource = "" } = {}) {
+  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 writeFile(
+    path.join(appRoot, "config", "public.js"),
+    configSource ||
+      `export const config = {
+  surfaceDefinitions: {
+    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"
+  );
+}
+
+test("ui-generator page subcommand creates an index page from an explicit target file", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        name: "Practice"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /<h1 class="text-h5 mb-2">Practice<\/h1>/);
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /id: "ui-generator\.page\.admin\.practice\.link"/);
+    assert.match(placementSource, /workspaceSuffix: "\/practice"/);
+    assert.match(placementSource, /label: "Practice"/);
+  });
+});
+
+test("ui-generator page subcommand creates a file route and derives label from the file path", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/contacts/[contactId].vue";
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /<h1 class="text-h5 mb-2">Contact Id<\/h1>/);
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /workspaceSuffix: "\/contacts\/\[contactId\]"/);
+    assert.match(placementSource, /id: "ui-generator\.page\.admin\.contacts\.contact-id\.link"/);
+    assert.match(placementSource, /label: "Contact Id"/);
+  });
+});
+
+test("ui-generator page subcommand supports link placement options", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/contacts/[contactId]/index/notes/index.vue";
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        "link-placement": "shell-layout:top-right",
+        "link-component-token": "local.main.ui.tab-link-item",
+        "link-to": "./notes"
+      }
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /host: "shell-layout"/);
+    assert.match(placementSource, /position: "top-right"/);
+    assert.match(placementSource, /componentToken: "local\.main\.ui\.tab-link-item"/);
+    assert.match(placementSource, /to: "\.\/notes"/);
+  });
+});
+
+test("ui-generator page subcommand infers subpage link placement, tab token, and link-to from the nearest parent host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const parentFile = "w/[workspaceSlug]/admin/contacts/[contactId].vue";
+    await mkdir(path.dirname(path.join(appRoot, toPagePath(parentFile))), { recursive: true });
+    await writeFile(
+      path.join(appRoot, toPagePath(parentFile)),
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="contact-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`,
+      "utf8"
+    );
+
+    const targetFile = "w/[workspaceSlug]/admin/contacts/[contactId]/notes/index.vue";
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /host: "contact-view"/);
+    assert.match(placementSource, /position: "sub-pages"/);
+    assert.match(placementSource, /componentToken: "local\.main\.ui\.tab-link-item"/);
+    assert.match(placementSource, /to: "\.\/notes"/);
+  });
+});
+
+test("ui-generator page subcommand prefers the nearest index-route parent host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await mkdir(path.join(appRoot, "src/pages/w/[workspaceSlug]/admin/catalog/index/products"), {
+      recursive: true
+    });
+    await writeFile(
+      path.join(appRoot, "src/pages/w/[workspaceSlug]/admin/catalog/index.vue"),
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="catalog" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`,
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "src/pages/w/[workspaceSlug]/admin/catalog/index/products/index.vue"),
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="catalog-products" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`,
+      "utf8"
+    );
+
+    const targetFile =
+      "w/[workspaceSlug]/admin/catalog/index/products/index/variants/index.vue";
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /host: "catalog-products"/);
+    assert.match(placementSource, /position: "sub-pages"/);
+    assert.match(placementSource, /componentToken: "local\.main\.ui\.tab-link-item"/);
+    assert.match(placementSource, /to: "\.\/variants"/);
+  });
+});
+
+test("ui-generator page subcommand chooses the most specific matching surface pagesRoot", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot, {
+      configSource: `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 }
+  }
+};
+`
+    });
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /id: "ui-generator\.page\.admin\.practice\.link"/);
+    assert.match(placementSource, /workspaceSuffix: "\/practice"/);
+  });
+});
+
+test("ui-generator page subcommand rejects unsupported options", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "page",
+        args: ["w/[workspaceSlug]/admin/practice/index.vue"],
+        options: {
+          bogus: "true"
+        }
+      }),
+      /ui-generator page received unsupported option: --bogus\./
+    );
+  });
+});
+
+test("ui-generator page subcommand rejects target files with a src/pages prefix", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "page",
+        args: ["src/pages/w/[workspaceSlug]/admin/practice/index.vue"],
+        options: {}
+      }),
+      /must be relative to src\/pages\/, without the src\/pages\/ prefix/
+    );
+  });
+});
+
+test("ui-generator page subcommand refuses to overwrite an existing page without --force", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await mkdir(path.join(appRoot, "src/pages/w/[workspaceSlug]/admin/practice"), {
+      recursive: true
+    });
+    await writeFile(
+      path.join(appRoot, toPagePath(targetFile)),
+      `<template>
+  <div>custom practice page</div>
+</template>
+`,
+      "utf8"
+    );
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "page",
+        args: [targetFile],
+        options: {
+          name: "Practice"
+        }
+      }),
+      /ui-generator page will not overwrite existing page src\/pages\/w\/\[workspaceSlug\]\/admin\/practice\/index\.vue\. Re-run with --force to overwrite it\./
+    );
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /custom practice page/);
+  });
+});
+
+test("ui-generator page subcommand overwrites an existing page when --force is passed", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await mkdir(path.join(appRoot, "src/pages/w/[workspaceSlug]/admin/practice"), {
+      recursive: true
+    });
+    await writeFile(
+      path.join(appRoot, toPagePath(targetFile)),
+      `<template>
+  <div>custom practice page</div>
+</template>
+`,
+      "utf8"
+    );
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        name: "Practice",
+        force: "true"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+    assert.equal(result.summary, 'Regenerated UI page "/practice" at src/pages/w/[workspaceSlug]/admin/practice/index.vue.');
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /<h1 class="text-h5 mb-2">Practice<\/h1>/);
+    assert.doesNotMatch(pageSource, /custom practice page/);
+  });
+});