@jskit-ai/ui-generator 0.1.14 → 0.1.16

package/src/server/subcommands/support.js

@@ -9,6 +9,9 @@ import { toCamelCase, toSnakeCase } from "@jskit-ai/kernel/shared/support/string
 const DEFAULT_COMPONENT_DIRECTORY = "src/components";
 const MAIN_CLIENT_PROVIDER_FILE = "packages/main/src/client/providers/MainClientProvider.js";
 const PLACEMENT_FILE = "src/placement.js";
+const SCRIPT_TAG_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+const SCRIPT_SETUP_ATTRIBUTE_PATTERN = /\bsetup\b/i;
+const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
 
 function toKebabCase(value = "") {
   return toSnakeCase(value).replaceAll("_", "-");
@@ -32,6 +35,85 @@ function requireOption(options = {}, optionName = "", { context = "ui-generator"
   return optionValue;
 }
 
+function requireSinglePositionalTargetFile(args = [], { context = "ui-generator" } = {}) {
+  const positionalArgs = Array.isArray(args) ? args.map((value) => normalizeText(value)).filter(Boolean) : [];
+  if (positionalArgs.length !== 1) {
+    throw new Error(`${context} requires exactly one <target-file> positional argument.`);
+  }
+
+  return positionalArgs[0];
+}
+
+function normalizeExplicitOutletTargetId(value = "") {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return "";
+  }
+
+  const separatorIndex = normalizedValue.indexOf(":");
+  if (separatorIndex <= 0 || separatorIndex >= normalizedValue.length - 1) {
+    return "";
+  }
+
+  const host = normalizeText(normalizedValue.slice(0, separatorIndex));
+  const position = normalizeText(normalizedValue.slice(separatorIndex + 1));
+  if (!host || !position) {
+    return "";
+  }
+
+  return `${host}:${position}`;
+}
+
+function resolveOutletTargetId(
+  rawTarget = "",
+  {
+    context = "ui-generator",
+    optionName = "target",
+    defaultPosition = ""
+  } = {}
+) {
+  const normalizedTarget = normalizeText(rawTarget);
+  if (!normalizedTarget) {
+    throw new Error(`${context} requires --${optionName}.`);
+  }
+
+  const targetId = normalizedTarget.includes(":")
+    ? normalizeExplicitOutletTargetId(normalizedTarget)
+    : normalizeExplicitOutletTargetId(`${normalizedTarget}:${normalizeText(defaultPosition)}`);
+  if (!targetId) {
+    throw new Error(`${context} option "${optionName}" must be "host" or "host:position".`);
+  }
+
+  const separatorIndex = targetId.indexOf(":");
+  return Object.freeze({
+    id: targetId,
+    host: targetId.slice(0, separatorIndex),
+    position: targetId.slice(separatorIndex + 1)
+  });
+}
+
+function rejectUnexpectedOptions(options = {}, allowedOptionNames = [], { context = "ui-generator" } = {}) {
+  const allowedOptionNameSet = new Set(
+    (Array.isArray(allowedOptionNames) ? allowedOptionNames : [])
+      .map((optionName) => normalizeText(optionName))
+      .filter(Boolean)
+  );
+
+  const unexpectedOptions = Object.keys(options || {})
+    .map((optionName) => normalizeText(optionName))
+    .filter(Boolean)
+    .filter((optionName) => !allowedOptionNameSet.has(optionName))
+    .sort((left, right) => left.localeCompare(right));
+
+  if (unexpectedOptions.length < 1) {
+    return;
+  }
+
+  throw new Error(
+    `${context} received unsupported option${unexpectedOptions.length > 1 ? "s" : ""}: ${unexpectedOptions.map((optionName) => `--${optionName}`).join(", ")}.`
+  );
+}
+
 function resolvePathWithinApp(appRoot, targetPath, { context = "ui-generator" } = {}) {
   const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
     context
@@ -150,6 +232,61 @@ function insertBeforeClassDeclaration(source = "", line = "", { className = "",
   };
 }
 
+function findScriptBlock(source = "") {
+  const sourceText = String(source || "");
+  let firstMatch = null;
+
+  for (const match of sourceText.matchAll(SCRIPT_TAG_PATTERN)) {
+    if (!firstMatch) {
+      firstMatch = match;
+    }
+
+    const attributesSource = String(match[1] || "");
+    if (SCRIPT_SETUP_ATTRIBUTE_PATTERN.test(attributesSource)) {
+      return Object.freeze({
+        index: match.index,
+        source: String(match[0] || ""),
+        attributesSource,
+        content: String(match[2] || "")
+      });
+    }
+  }
+
+  if (!firstMatch) {
+    return null;
+  }
+
+  return Object.freeze({
+    index: firstMatch.index,
+    source: String(firstMatch[0] || ""),
+    attributesSource: String(firstMatch[1] || ""),
+    content: String(firstMatch[2] || "")
+  });
+}
+
+function parseTagAttributes(attributesSource = "") {
+  const attributes = {};
+  const source = String(attributesSource || "");
+  for (const match of source.matchAll(ATTRIBUTE_PATTERN)) {
+    const attributeName = normalizeText(match[1]);
+    if (!attributeName) {
+      continue;
+    }
+    const hasValue = match[2] != null || match[3] != null;
+    attributes[attributeName] = hasValue ? String(match[2] ?? match[3] ?? "") : true;
+  }
+  return attributes;
+}
+
+function indentBlock(source = "", indent = "") {
+  const sourceText = String(source || "");
+  const indentation = String(indent || "");
+  return sourceText
+    .split("\n")
+    .map((line) => `${indentation}${line}`)
+    .join("\n");
+}
+
 export {
   DEFAULT_COMPONENT_DIRECTORY,
   MAIN_CLIENT_PROVIDER_FILE,
@@ -157,9 +294,16 @@ export {
   toKebabCase,
   toPascalCase,
   requireOption,
+  requireSinglePositionalTargetFile,
+  normalizeExplicitOutletTargetId,
+  resolveOutletTargetId,
+  rejectUnexpectedOptions,
   resolvePathWithinApp,
   ensureTrailingNewline,
   appendBlockIfMarkerMissing,
   insertImportIfMissing,
-  insertBeforeClassDeclaration
+  insertBeforeClassDeclaration,
+  findScriptBlock,
+  parseTagAttributes,
+  indentBlock
 };

package/test/addSubpagesSubcommand.test.js

@@ -0,0 +1,321 @@
+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/addSubpages.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-add-subpages-"));
+  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: {
+    admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true, requiresAuth: true, requiresWorkspace: true }
+  }
+};
+`,
+    "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"
+  );
+}
+
+async function writePageFile(appRoot, targetFile, source = "<template><section /></template>\n") {
+  const targetPath = path.join(appRoot, "src/pages", targetFile);
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, source, "utf8");
+  return targetPath;
+}
+
+async function readPageFile(appRoot, targetFile) {
+  return readFile(path.join(appRoot, "src/pages", targetFile), "utf8");
+}
+
+test("ui-generator add-subpages derives the default target from an index-route page path", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(
+      appRoot,
+      targetFile,
+      `<template>
+  <section class="pa-4">
+    <h1 class="text-h5 mb-2">Practice</h1>
+  </section>
+</template>
+`
+    );
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {
+        title: "Practice",
+        subtitle: "Manage practice modules."
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [
+      "packages/main/src/client/providers/MainClientProvider.js",
+      "src/components/SectionContainerShell.vue",
+      "src/components/TabLinkItem.vue",
+      `src/pages/${targetFile}`
+    ]);
+
+    const pageSource = await readPageFile(appRoot, targetFile);
+    assert.match(pageSource, /<ShellOutlet host="practice" position="sub-pages" \/>/);
+    assert.match(pageSource, /<RouterView \/>/);
+  });
+});
+
+test("ui-generator add-subpages derives the default target from a dynamic file-route page path", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/contacts/[contactId].vue";
+    await writePageFile(appRoot, targetFile);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {}
+    });
+
+    const pageSource = await readPageFile(appRoot, targetFile);
+    assert.match(pageSource, /<ShellOutlet host="contacts-contact-id" position="sub-pages" \/>/);
+  });
+});
+
+test("ui-generator add-subpages derives the default target from a nested route path", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/catalog/products/index.vue";
+    await writePageFile(appRoot, targetFile);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {}
+    });
+
+    const pageSource = await readPageFile(appRoot, targetFile);
+    assert.match(pageSource, /<ShellOutlet host="catalog-products" position="sub-pages" \/>/);
+  });
+});
+
+test("ui-generator add-subpages supports explicit target host shorthand", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(appRoot, targetFile);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {
+        target: "practice-hub"
+      }
+    });
+
+    const pageSource = await readPageFile(appRoot, targetFile);
+    assert.match(pageSource, /<ShellOutlet host="practice-hub" position="sub-pages" \/>/);
+  });
+});
+
+test("ui-generator add-subpages supports explicit target host:position", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(appRoot, targetFile);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {
+        target: "practice-hub:secondary-tabs"
+      }
+    });
+
+    const pageSource = await readPageFile(appRoot, targetFile);
+    assert.match(pageSource, /<ShellOutlet host="practice-hub" position="secondary-tabs" \/>/);
+  });
+});
+
+test("ui-generator add-subpages does not rewrite existing scaffold support components", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(appRoot, targetFile);
+    const customSectionShellSource = `<template><section class="custom-shell"><slot /></section></template>\n`;
+    const customTabLinkSource = `<template><button class="custom-tab-link"><slot /></button></template>\n`;
+    await writeFile(
+      path.join(appRoot, "src", "components", "SectionContainerShell.vue"),
+      customSectionShellSource,
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "src", "components", "TabLinkItem.vue"),
+      customTabLinkSource,
+      "utf8"
+    );
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {
+        title: "Practice"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [
+      "packages/main/src/client/providers/MainClientProvider.js",
+      `src/pages/${targetFile}`
+    ]);
+    assert.equal(
+      await readFile(path.join(appRoot, "src", "components", "SectionContainerShell.vue"), "utf8"),
+      customSectionShellSource
+    );
+    assert.equal(
+      await readFile(path.join(appRoot, "src", "components", "TabLinkItem.vue"), "utf8"),
+      customTabLinkSource
+    );
+  });
+});
+
+test("ui-generator add-subpages fails if subpages are already enabled", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(appRoot, targetFile);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {}
+    });
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: [targetFile],
+        options: {}
+      }),
+      /found existing RouterView.*Subpages are already enabled/
+    );
+  });
+});
+
+test("ui-generator add-subpages rejects files outside src/pages", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+    await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
+    await writeFile(path.join(appRoot, "src", "components", "Panel.vue"), "<template><div /></template>\n", "utf8");
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: ["components/Panel.vue"],
+        options: {}
+      }),
+      /must be relative to src\/pages\/ and resolve to a configured surface/
+    );
+  });
+});
+
+test("ui-generator add-subpages validates target format", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(appRoot, targetFile);
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: [targetFile],
+        options: {
+          target: "practice:"
+        }
+      }),
+      /option "target" must be "host" or "host:position"/
+    );
+  });
+});
+
+test("ui-generator add-subpages rejects target files with a src/pages prefix", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: ["src/pages/w/[workspaceSlug]/admin/practice/index.vue"],
+        options: {}
+      }),
+      /must be relative to src\/pages\/, without the src\/pages\/ prefix/
+    );
+  });
+});