@jskit-ai/ui-generator 0.1.14 → 0.1.16

package/src/server/subcommands/element.js

@@ -4,7 +4,7 @@ import {
   resolveShellOutletPlacementTargetFromApp,
   toPosixPath
 } from "@jskit-ai/kernel/server/support";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeBoolean, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   DEFAULT_COMPONENT_DIRECTORY,
   MAIN_CLIENT_PROVIDER_FILE,
@@ -12,12 +12,15 @@ import {
   toKebabCase,
   toPascalCase,
   requireOption,
+  rejectUnexpectedOptions,
   resolvePathWithinApp,
   appendBlockIfMarkerMissing,
   insertImportIfMissing,
   insertBeforeClassDeclaration
 } from "./support.js";
 
+const DEFAULT_ELEMENT_PLACEMENT = "shell-layout:top-right";
+
 function renderElementComponentSource(elementName = "") {
   return `<template>
   <section class="pa-4">
@@ -36,40 +39,47 @@ async function runGeneratorSubcommand({
   dryRun = false
 } = {}) {
   const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
-  if (normalizedSubcommand !== "element") {
+  if (normalizedSubcommand !== "placed-element") {
     throw new Error(`Unsupported ui-generator subcommand: ${normalizedSubcommand || "<empty>"}.`);
   }
   if (Array.isArray(args) && args.length > 0) {
-    throw new Error("ui-generator element does not accept positional arguments.");
+    throw new Error("ui-generator placed-element does not accept positional arguments.");
   }
+  rejectUnexpectedOptions(options, ["name", "surface", "path", "placement", "force"], {
+    context: "ui-generator placed-element"
+  });
 
-  const name = requireOption(options, "name", { context: "ui-generator element" });
-  const surface = requireOption(options, "surface", { context: "ui-generator element" }).toLowerCase();
+  const name = requireOption(options, "name", { context: "ui-generator placed-element" });
+  const surface = requireOption(options, "surface", { context: "ui-generator placed-element" }).toLowerCase();
   const componentDirectory = normalizeText(options.path) || DEFAULT_COMPONENT_DIRECTORY;
+  const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")
+    ? normalizeBoolean(options.force)
+    : false;
   const elementNamePascal = toPascalCase(name);
   const elementNameKebab = toKebabCase(name);
 
   if (!elementNamePascal || !elementNameKebab) {
-    throw new Error("ui-generator element requires a valid --name.");
+    throw new Error("ui-generator placed-element requires a valid --name.");
   }
 
   const componentPath = resolvePathWithinApp(appRoot, path.join(componentDirectory, `${elementNamePascal}Element.vue`), {
-    context: "ui-generator element"
+    context: "ui-generator placed-element"
   });
   const providerPath = resolvePathWithinApp(appRoot, MAIN_CLIENT_PROVIDER_FILE, {
-    context: "ui-generator element"
+    context: "ui-generator placed-element"
   });
   const placementPath = resolvePathWithinApp(appRoot, PLACEMENT_FILE, {
-    context: "ui-generator element"
+    context: "ui-generator placed-element"
   });
   const componentToken = `local.main.ui.element.${elementNameKebab}`;
   const placementTarget = await resolveShellOutletPlacementTargetFromApp({
     appRoot,
     context: "ui-generator",
-    placement: options?.placement
+    placement: options?.placement || DEFAULT_ELEMENT_PLACEMENT
   });
 
   const touchedFiles = new Set();
+  const desiredComponentSource = renderElementComponentSource(name);
 
   let componentSource = "";
   try {
@@ -77,10 +87,15 @@ async function runGeneratorSubcommand({
   } catch {
     componentSource = "";
   }
-  if (!componentSource) {
+  if (componentSource && !forceOverwrite) {
+    throw new Error(
+      `ui-generator placed-element will not overwrite existing component file ${componentPath.relativePath}. Re-run with --force to overwrite it.`
+    );
+  }
+  if (!componentSource || (forceOverwrite && componentSource !== desiredComponentSource)) {
     if (dryRun !== true) {
       await mkdir(path.dirname(componentPath.absolutePath), { recursive: true });
-      await writeFile(componentPath.absolutePath, renderElementComponentSource(name), "utf8");
+      await writeFile(componentPath.absolutePath, desiredComponentSource, "utf8");
     }
     touchedFiles.add(componentPath.relativePath);
   }
@@ -88,7 +103,7 @@ async function runGeneratorSubcommand({
   const providerSource = await readFile(providerPath.absolutePath, "utf8");
   if (!/\bregisterMainClientComponent\s*\(/.test(providerSource)) {
     throw new Error(
-      `ui-generator element could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
+      `ui-generator placed-element could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
     );
   }
 
@@ -140,8 +155,8 @@ async function runGeneratorSubcommand({
     touchedFiles: touchedFileList,
     summary:
       touchedFileList.length > 0
-        ? `Generated UI element "${elementNameKebab}" and placement token "${componentToken}".`
-        : `UI element "${elementNameKebab}" is already up to date.`
+        ? `Generated placed UI element "${elementNameKebab}" and placement token "${componentToken}".`
+        : `Placed UI element "${elementNameKebab}" is already up to date.`
   };
 }
 

package/src/server/subcommands/outlet.js

@@ -1,91 +1,22 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
-  requireOption,
+  requireSinglePositionalTargetFile,
+  rejectUnexpectedOptions,
+  resolveOutletTargetId,
   resolvePathWithinApp,
   ensureTrailingNewline,
-  insertImportIfMissing
+  insertImportIfMissing,
+  findScriptBlock,
+  parseTagAttributes,
+  indentBlock
 } from "./support.js";
 
 const DEFAULT_OUTLET_POSITION = "sub-pages";
-const MODE_ROUTED = "routed";
-const MODE_OUTLET_ONLY = "outlet-only";
 
-const SCRIPT_TAG_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
 const ROUTE_TAG_PATTERN = /<route\b[^>]*>[\s\S]*?<\/route>\s*/gi;
 const TEMPLATE_CLOSE_TAG_PATTERN = /<\/template>/gi;
-const ROUTER_VIEW_TAG_PATTERN = /<RouterView(?:\s|\/|>)/;
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/gi;
-const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
-const SCRIPT_SETUP_ATTRIBUTE_PATTERN = /\bsetup\b/i;
-
-function resolveOutletMode(rawMode = "") {
-  const normalized = String(rawMode || "").trim().toLowerCase();
-  if (!normalized || normalized === MODE_ROUTED) {
-    return MODE_ROUTED;
-  }
-  if (normalized === MODE_OUTLET_ONLY || normalized === "outlet") {
-    return MODE_OUTLET_ONLY;
-  }
-
-  throw new Error(`ui-generator outlet received unsupported --mode value: ${rawMode}. Use routed or outlet-only.`);
-}
-
-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 hasImportFromModule(source = "", modulePath = "") {
-  const normalizedModulePath = String(modulePath || "").trim();
-  if (!normalizedModulePath) {
-    return false;
-  }
-
-  const sourceText = String(source || "");
-  return sourceText.includes(`from "${normalizedModulePath}"`) || sourceText.includes(`from '${normalizedModulePath}'`);
-}
-
-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 hasShellOutletTarget(source = "", { host = "", position = "" } = {}) {
   const normalizedHost = normalizeText(host);
@@ -106,19 +37,14 @@ function hasShellOutletTarget(source = "", { host = "", position = "" } = {}) {
   return false;
 }
 
-function applyScriptImports(source = "", { includeRouterViewImport = false } = {}) {
+function applyScriptImports(source = "") {
   const sourceText = String(source || "");
   const scriptBlock = findScriptBlock(sourceText);
 
   const shellOutletImport = "import ShellOutlet from \"@jskit-ai/shell-web/client/components/ShellOutlet\";";
-  const routerViewImport = "import { RouterView } from \"vue-router\";";
 
   if (!scriptBlock) {
-    const importLines = [shellOutletImport];
-    if (includeRouterViewImport) {
-      importLines.push(routerViewImport);
-    }
-    const scriptSetupBlock = `<script setup>\n${importLines.join("\n")}\n</script>\n`;
+    const scriptSetupBlock = `<script setup>\n${shellOutletImport}\n</script>\n`;
     let insertionIndex = 0;
     for (const match of sourceText.matchAll(ROUTE_TAG_PATTERN)) {
       insertionIndex = match.index + String(match[0] || "").length;
@@ -133,15 +59,7 @@ function applyScriptImports(source = "", { includeRouterViewImport = false } = {
   let nextScriptContent = scriptBlock.content;
   const shellImportApplied = insertImportIfMissing(nextScriptContent, shellOutletImport);
   nextScriptContent = shellImportApplied.content;
-
-  let routerImportChanged = false;
-  if (includeRouterViewImport && !hasImportFromModule(nextScriptContent, "vue-router")) {
-    const routerImportApplied = insertImportIfMissing(nextScriptContent, routerViewImport);
-    nextScriptContent = routerImportApplied.content;
-    routerImportChanged = routerImportApplied.changed;
-  }
-
-  if (!shellImportApplied.changed && !routerImportChanged) {
+  if (!shellImportApplied.changed) {
     return {
       changed: false,
       content: sourceText
@@ -157,23 +75,8 @@ function applyScriptImports(source = "", { includeRouterViewImport = false } = {
   };
 }
 
-function createOutletBlock({ host = "", position = "", includeRouterView = false } = {}) {
-  const lines = [
-    `<ShellOutlet host=\"${host}\" position=\"${position}\" />`
-  ];
-  if (includeRouterView) {
-    lines.push("<RouterView />");
-  }
-  return lines.join("\n");
-}
-
-function indentBlock(source = "", indent = "") {
-  const sourceText = String(source || "");
-  const indentation = String(indent || "");
-  return sourceText
-    .split("\n")
-    .map((line) => `${indentation}${line}`)
-    .join("\n");
+function createOutletBlock({ host = "", position = "" } = {}) {
+  return `<ShellOutlet host=\"${host}\" position=\"${position}\" />`;
 }
 
 function findLastTemplateCloseTag(source = "") {
@@ -185,9 +88,9 @@ function findLastTemplateCloseTag(source = "") {
   return lastMatch;
 }
 
-function applyOutletTemplateBlock(source = "", { host = "", position = "", includeRouterView = false } = {}) {
+function applyOutletTemplateBlock(source = "", { host = "", position = "" } = {}) {
   const sourceText = String(source || "");
-  const outletBlock = createOutletBlock({ host, position, includeRouterView });
+  const outletBlock = createOutletBlock({ host, position });
 
   const templateTagMatch = findLastTemplateCloseTag(sourceText);
   if (!templateTagMatch) {
@@ -223,18 +126,26 @@ async function runGeneratorSubcommand({
   if (normalizedSubcommand !== "outlet") {
     throw new Error(`Unsupported ui-generator subcommand: ${normalizedSubcommand || "<empty>"}.`);
   }
-  if (Array.isArray(args) && args.length > 0) {
-    throw new Error("ui-generator outlet does not accept positional arguments.");
-  }
+  const targetFile = requireSinglePositionalTargetFile(args, { context: "ui-generator outlet" });
+  rejectUnexpectedOptions(options, ["target"], {
+    context: "ui-generator outlet"
+  });
 
-  const targetFile = requireOption(options, "file", { context: "ui-generator outlet" });
-  const host = requireOption(options, "host", { context: "ui-generator outlet" });
-  const position = normalizeText(options?.position) || DEFAULT_OUTLET_POSITION;
-  const mode = resolveOutletMode(options?.mode);
+  const outletTarget = resolveOutletTargetId(options?.target, {
+    context: "ui-generator outlet",
+    optionName: "target",
+    defaultPosition: DEFAULT_OUTLET_POSITION
+  });
+  const { host, position } = outletTarget;
 
   const targetFilePath = resolvePathWithinApp(appRoot, targetFile, {
     context: "ui-generator outlet"
   });
+  if (!targetFilePath.relativePath.toLowerCase().endsWith(".vue")) {
+    throw new Error(
+      `ui-generator outlet target file must be an existing Vue SFC (.vue): ${targetFilePath.relativePath}.`
+    );
+  }
 
   let source = "";
   try {
@@ -244,19 +155,13 @@ async function runGeneratorSubcommand({
   }
 
   const hasTargetOutlet = hasShellOutletTarget(source, { host, position });
-  const hasRouterView = ROUTER_VIEW_TAG_PATTERN.test(source);
-  const shouldInsertRouterView = mode === MODE_ROUTED && !hasRouterView && !hasTargetOutlet;
-
   const templateApplied = hasTargetOutlet
     ? { changed: false, content: source }
     : applyOutletTemplateBlock(source, {
       host,
-      position,
-      includeRouterView: shouldInsertRouterView
+      position
     });
-  const scriptApplied = applyScriptImports(templateApplied.content, {
-    includeRouterViewImport: shouldInsertRouterView
-  });
+  const scriptApplied = applyScriptImports(templateApplied.content);
 
   const changed = templateApplied.changed || scriptApplied.changed;
   if (changed && dryRun !== true) {

package/src/server/subcommands/page.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { normalizeBoolean, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { buildUiPageTemplateContext } from "../buildTemplateContext.js";
+import {
+  PLACEMENT_FILE,
+  requireSinglePositionalTargetFile,
+  rejectUnexpectedOptions,
+  resolvePathWithinApp,
+  appendBlockIfMarkerMissing
+} from "./support.js";
+import {
+  resolvePageTargetDetails,
+  renderPlainPageSource
+} from "./pageSupport.js";
+
+function renderPageLinkPlacementBlock({
+  marker = "",
+  context = {},
+  label = "",
+  surface = ""
+} = {}) {
+  return (
+    `// ${marker}\n` +
+    "{\n" +
+    "  addPlacement({\n" +
+    `    id: "${context.__JSKIT_UI_LINK_PLACEMENT_ID__}",\n` +
+    `    host: "${context.__JSKIT_UI_LINK_PLACEMENT_HOST__}",\n` +
+    `    position: "${context.__JSKIT_UI_LINK_PLACEMENT_POSITION__}",\n` +
+    `    surfaces: ["${surface}"],\n` +
+    "    order: 155,\n" +
+    `    componentToken: "${context.__JSKIT_UI_LINK_COMPONENT_TOKEN__}",\n` +
+    "    props: {\n" +
+    `      label: "${label}",\n` +
+    `      surface: "${surface}",\n` +
+    `      workspaceSuffix: "${context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__}",\n` +
+    `      nonWorkspaceSuffix: "${context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__}",\n` +
+    `${context.__JSKIT_UI_LINK_TO_PROP_LINE__}    },\n` +
+    "    when: ({ auth }) => Boolean(auth?.authenticated)\n" +
+    "  });\n" +
+    "}\n"
+  );
+}
+
+async function runGeneratorSubcommand({
+  appRoot,
+  subcommand = "",
+  args = [],
+  options = {},
+  dryRun = false
+} = {}) {
+  const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand !== "page") {
+    throw new Error(`Unsupported ui-generator subcommand: ${normalizedSubcommand || "<empty>"}.`);
+  }
+  const targetFile = requireSinglePositionalTargetFile(args, { context: "ui-generator page" });
+  rejectUnexpectedOptions(
+    options,
+    ["name", "link-placement", "link-component-token", "link-to", "force"],
+    { context: "ui-generator page" }
+  );
+
+  const pageTarget = await resolvePageTargetDetails({
+    appRoot,
+    targetFile,
+    context: "ui-generator page"
+  });
+  const pageLabel = normalizeText(options?.name) || pageTarget.defaultName;
+  const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")
+    ? normalizeBoolean(options.force)
+    : false;
+  const pageFilePath = pageTarget.targetFilePath.absolutePath;
+  const pageRelativePath = pageTarget.targetFilePath.relativePath;
+
+  const touchedFiles = new Set();
+  let pageAlreadyExisted = true;
+  try {
+    await readFile(pageFilePath, "utf8");
+  } catch {
+    pageAlreadyExisted = false;
+  }
+
+  if (pageAlreadyExisted && !forceOverwrite) {
+    throw new Error(
+      `ui-generator page will not overwrite existing page ${pageRelativePath}. Re-run with --force to overwrite it.`
+    );
+  }
+
+  const placementContext = await buildUiPageTemplateContext({
+    appRoot: pageTarget.appRoot,
+    targetFile,
+    options
+  });
+  const placementPath = resolvePathWithinApp(pageTarget.appRoot, PLACEMENT_FILE, {
+    context: "ui-generator page"
+  });
+  const placementSource = await readFile(placementPath.absolutePath, "utf8");
+  const placementMarker = `jskit:ui-generator.page.link:${pageTarget.surfaceId}:${pageTarget.routeUrlSuffix}`;
+  const placementApplied = appendBlockIfMarkerMissing(
+    placementSource,
+    placementMarker,
+    renderPageLinkPlacementBlock({
+      marker: placementMarker,
+      context: placementContext,
+      label: pageLabel,
+      surface: pageTarget.surfaceId
+    })
+  );
+
+  if (!pageAlreadyExisted || forceOverwrite) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(pageFilePath), { recursive: true });
+      await writeFile(pageFilePath, renderPlainPageSource(pageLabel), "utf8");
+    }
+    touchedFiles.add(pageRelativePath);
+  }
+
+  if (placementApplied.changed) {
+    if (dryRun !== true) {
+      await writeFile(placementPath.absolutePath, placementApplied.content, "utf8");
+    }
+    touchedFiles.add(placementPath.relativePath);
+  }
+
+  const touchedFileList = [...touchedFiles].sort((left, right) => left.localeCompare(right));
+  return {
+    touchedFiles: touchedFileList,
+    summary: !pageAlreadyExisted
+      ? `Generated UI page "${pageTarget.routeUrlSuffix}" at ${pageRelativePath}.`
+      : `Regenerated UI page "${pageTarget.routeUrlSuffix}" at ${pageRelativePath}.`
+  };
+}
+
+export { runGeneratorSubcommand };