@jskit-ai/ui-generator 0.1.3

package/src/server/subcommands/container.js

@@ -0,0 +1,481 @@
+import path from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import {
+  resolveRequiredAppRoot,
+  resolveShellOutletPlacementTargetFromApp,
+  toPosixPath
+} from "@jskit-ai/kernel/server/support";
+import {
+  normalizeObject,
+  normalizeText
+} from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  DEFAULT_COMPONENT_DIRECTORY,
+  MAIN_CLIENT_PROVIDER_FILE,
+  PLACEMENT_FILE,
+  toKebabCase,
+  requireOption,
+  resolvePathWithinApp,
+  appendBlockIfMarkerMissing,
+  insertImportIfMissing,
+  insertBeforeClassDeclaration
+} from "./support.js";
+
+const CONTAINER_OUTLET_POSITION = "sub-pages";
+const SECTION_CONTAINER_SHELL_COMPONENT = "SectionContainerShell";
+const SECTION_TAB_LINK_COMPONENT = "SectionShellTabLinkItem";
+const SECTION_TAB_LINK_COMPONENT_TOKEN = "local.main.ui.section-shell.tab-link-item";
+
+function normalizeRoutePrefix(value = "") {
+  const source = normalizeText(value).replaceAll("\\", "/");
+  if (!source) {
+    return "";
+  }
+
+  const parts = source
+    .split("/")
+    .map((entry) => toKebabCase(entry))
+    .filter(Boolean);
+  return parts.join("/");
+}
+
+async function loadPublicConfig(appRoot = "") {
+  const configPath = path.join(appRoot, "config", "public.js");
+
+  try {
+    await readFile(configPath, "utf8");
+  } catch {
+    throw new Error("ui-generator container requires app config at config/public.js.");
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await import(`${pathToFileURL(configPath).href}?t=${Date.now()}_${Math.random()}`);
+  } catch (error) {
+    throw new Error(
+      `ui-generator container could not load config/public.js: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const config = normalizeObject(
+    moduleNamespace?.config ||
+    moduleNamespace?.default?.config ||
+    moduleNamespace?.default
+  );
+  if (Object.keys(config).length < 1) {
+    throw new Error("ui-generator container requires exported config in config/public.js.");
+  }
+
+  return config;
+}
+
+async function resolveSurfacePagesDirectory(appRoot = "", surfaceId = "") {
+  const config = await loadPublicConfig(appRoot);
+  const surfaceDefinitions = normalizeObject(config.surfaceDefinitions);
+  const normalizedSurfaceId = normalizeText(surfaceId).toLowerCase();
+  const surfaceDefinition = normalizeObject(surfaceDefinitions[normalizedSurfaceId]);
+  if (Object.keys(surfaceDefinition).length < 1) {
+    throw new Error(`ui-generator container surface "${normalizedSurfaceId}" is not defined in config/public.js.`);
+  }
+  if (surfaceDefinition.enabled === false) {
+    throw new Error(`ui-generator container surface "${normalizedSurfaceId}" is disabled in config/public.js.`);
+  }
+
+  const pagesRoot = normalizeText(surfaceDefinition.pagesRoot);
+  if (!pagesRoot) {
+    return path.join(appRoot, "src", "pages");
+  }
+  return path.join(appRoot, "src", "pages", pagesRoot);
+}
+
+function renderSectionContainerShellSource() {
+  return `<script setup>
+import { computed } from "vue";
+import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
+
+const props = defineProps({
+  title: {
+    type: String,
+    default: ""
+  },
+  subtitle: {
+    type: String,
+    default: ""
+  },
+  host: {
+    type: String,
+    default: ""
+  },
+  position: {
+    type: String,
+    default: "${CONTAINER_OUTLET_POSITION}"
+  }
+});
+
+const resolvedTitle = computed(() => String(props.title || "").trim() || "Section");
+const resolvedSubtitle = computed(() => String(props.subtitle || "").trim());
+</script>
+
+<template>
+  <section class="section-container-shell d-flex flex-column ga-4">
+    <v-card rounded="lg" elevation="1" border>
+      <v-card-item>
+        <v-card-title class="px-0">{{ resolvedTitle }}</v-card-title>
+        <v-card-subtitle v-if="resolvedSubtitle" class="px-0">{{ resolvedSubtitle }}</v-card-subtitle>
+      </v-card-item>
+      <v-divider />
+      <v-card-text class="section-container-shell__tabs">
+        <ShellOutlet :host="props.host" :position="props.position" />
+      </v-card-text>
+    </v-card>
+
+    <slot />
+  </section>
+</template>
+
+<style scoped>
+.section-container-shell__tabs {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  overflow-x: auto;
+  padding: 0.75rem;
+  scrollbar-width: thin;
+}
+
+.section-container-shell__tabs :deep(.section-shell-tab-link) {
+  flex: 0 0 auto;
+}
+
+@media (max-width: 640px) {
+  .section-container-shell__tabs {
+    gap: 0.375rem;
+    padding: 0.5rem;
+  }
+}
+</style>
+`;
+}
+
+function renderSectionShellTabLinkItemSource() {
+  return `<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { usePaths } from "@jskit-ai/users-web/client/composables/usePaths";
+import { useWorkspaceRouteContext } from "@jskit-ai/users-web/client/composables/useWorkspaceRouteContext";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  workspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  nonWorkspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  }
+});
+
+const route = useRoute();
+const paths = usePaths();
+const { currentSurfaceId, workspaceSlugFromRoute } = useWorkspaceRouteContext();
+
+function normalizePathname(pathname = "") {
+  const source = String(pathname || "").trim();
+  if (!source) {
+    return "";
+  }
+
+  const queryIndex = source.indexOf("?");
+  const hashIndex = source.indexOf("#");
+  const cutoff =
+    queryIndex < 0
+      ? hashIndex
+      : hashIndex < 0
+        ? queryIndex
+        : Math.min(queryIndex, hashIndex);
+  return cutoff < 0 ? source : source.slice(0, cutoff);
+}
+
+const targetSurfaceId = computed(() => {
+  const explicitSurface = String(props.surface || "").trim().toLowerCase();
+  if (explicitSurface && explicitSurface !== "*") {
+    return explicitSurface;
+  }
+  return String(currentSurfaceId.value || paths.currentSurfaceId.value || "").trim().toLowerCase();
+});
+
+const resolvedTo = computed(() => {
+  const explicitTo = String(props.to || "").trim();
+  if (explicitTo) {
+    return explicitTo;
+  }
+
+  const workspaceSlug = String(workspaceSlugFromRoute.value || "").trim();
+  const suffix = workspaceSlug ? props.workspaceSuffix : props.nonWorkspaceSuffix;
+  const normalizedSuffix = String(suffix || "/").trim() || "/";
+  return paths.page(normalizedSuffix, {
+    surface: targetSurfaceId.value,
+    mode: "auto"
+  });
+});
+
+const isActive = computed(() => {
+  const targetPathname = normalizePathname(resolvedTo.value);
+  const currentPathname = normalizePathname(route.fullPath || route.path);
+  if (!targetPathname || !currentPathname) {
+    return false;
+  }
+  return currentPathname === targetPathname || currentPathname.startsWith(\`\${targetPathname}/\`);
+});
+</script>
+
+<template>
+  <v-btn
+    v-if="resolvedTo"
+    class="section-shell-tab-link text-none"
+    :to="resolvedTo"
+    rounded="pill"
+    size="small"
+    :variant="isActive ? 'flat' : 'tonal'"
+    :color="isActive ? 'primary' : undefined"
+    :disabled="props.disabled"
+    :aria-current="isActive ? 'page' : undefined"
+  >
+    {{ props.label }}
+  </v-btn>
+</template>
+`;
+}
+
+function renderContainerPageSource({
+  surface = "",
+  title = "",
+  subtitle = "",
+  containerHost = "",
+  containerPosition = CONTAINER_OUTLET_POSITION,
+  sectionContainerComponentImportPath = "/src/components/SectionContainerShell.vue"
+} = {}) {
+  return `<script setup>
+import { RouterView } from "vue-router";
+import SectionContainerShell from "${sectionContainerComponentImportPath}";
+</script>
+
+<template>
+  <SectionContainerShell
+    title="${title}"
+    subtitle="${subtitle}"
+    host="${containerHost}"
+    position="${containerPosition}"
+  >
+    <RouterView />
+  </SectionContainerShell>
+</template>
+
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "${surface}"
+    }
+  }
+}
+</route>
+`;
+}
+
+async function runGeneratorSubcommand({
+  appRoot,
+  subcommand = "",
+  args = [],
+  options = {},
+  dryRun = false
+} = {}) {
+  const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand !== "container") {
+    throw new Error(`Unsupported ui-generator subcommand: ${normalizedSubcommand || "<empty>"}.`);
+  }
+  if (Array.isArray(args) && args.length > 0) {
+    throw new Error("ui-generator container does not accept positional arguments.");
+  }
+
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context: "ui-generator container"
+  });
+  const name = requireOption(options, "name", { context: "ui-generator container" });
+  const surface = requireOption(options, "surface", { context: "ui-generator container" }).toLowerCase();
+  const routePrefix = normalizeRoutePrefix(options?.["directory-prefix"]);
+  const componentDirectory = normalizeText(options?.path) || DEFAULT_COMPONENT_DIRECTORY;
+  const containerSlug = toKebabCase(name);
+  if (!containerSlug) {
+    throw new Error("ui-generator container requires a valid --name.");
+  }
+
+  const routePath = routePrefix ? `${routePrefix}/${containerSlug}` : containerSlug;
+  const pagesDirectory = await resolveSurfacePagesDirectory(resolvedAppRoot, surface);
+  const containerFilePath = path.join(pagesDirectory, `${routePath}.vue`);
+  const containerRelativePath = toPosixPath(path.relative(resolvedAppRoot, containerFilePath));
+  const placementPath = resolvePathWithinApp(resolvedAppRoot, PLACEMENT_FILE, {
+    context: "ui-generator container"
+  });
+  const providerPath = resolvePathWithinApp(resolvedAppRoot, MAIN_CLIENT_PROVIDER_FILE, {
+    context: "ui-generator container"
+  });
+  const sectionContainerShellPath = resolvePathWithinApp(
+    resolvedAppRoot,
+    path.join(componentDirectory, `${SECTION_CONTAINER_SHELL_COMPONENT}.vue`),
+    {
+      context: "ui-generator container"
+    }
+  );
+  const sectionTabLinkPath = resolvePathWithinApp(
+    resolvedAppRoot,
+    path.join(componentDirectory, `${SECTION_TAB_LINK_COMPONENT}.vue`),
+    {
+      context: "ui-generator container"
+    }
+  );
+
+  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
+    appRoot: resolvedAppRoot,
+    context: "ui-generator container",
+    placement: options?.placement
+  });
+
+  const touchedFiles = new Set();
+
+  let existingSectionContainerSource = "";
+  try {
+    existingSectionContainerSource = await readFile(sectionContainerShellPath.absolutePath, "utf8");
+  } catch {
+    existingSectionContainerSource = "";
+  }
+  if (!existingSectionContainerSource) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(sectionContainerShellPath.absolutePath), { recursive: true });
+      await writeFile(sectionContainerShellPath.absolutePath, renderSectionContainerShellSource(), "utf8");
+    }
+    touchedFiles.add(sectionContainerShellPath.relativePath);
+  }
+
+  let existingSectionTabLinkSource = "";
+  try {
+    existingSectionTabLinkSource = await readFile(sectionTabLinkPath.absolutePath, "utf8");
+  } catch {
+    existingSectionTabLinkSource = "";
+  }
+  if (!existingSectionTabLinkSource) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(sectionTabLinkPath.absolutePath), { recursive: true });
+      await writeFile(sectionTabLinkPath.absolutePath, renderSectionShellTabLinkItemSource(), "utf8");
+    }
+    touchedFiles.add(sectionTabLinkPath.relativePath);
+  }
+
+  const providerSource = await readFile(providerPath.absolutePath, "utf8");
+  if (!/\bregisterMainClientComponent\s*\(/.test(providerSource)) {
+    throw new Error(
+      `ui-generator container could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
+    );
+  }
+
+  const providerImportLine = `import ${SECTION_TAB_LINK_COMPONENT} from "/${toPosixPath(path.join(componentDirectory, `${SECTION_TAB_LINK_COMPONENT}.vue`))}";`;
+  const providerRegisterLine =
+    `registerMainClientComponent("${SECTION_TAB_LINK_COMPONENT_TOKEN}", () => ${SECTION_TAB_LINK_COMPONENT});`;
+  const providerImportApplied = insertImportIfMissing(providerSource, providerImportLine);
+  const providerRegisterApplied = insertBeforeClassDeclaration(
+    providerImportApplied.content,
+    providerRegisterLine,
+    {
+      className: "MainClientProvider",
+      contextFile: MAIN_CLIENT_PROVIDER_FILE
+    }
+  );
+  if (providerImportApplied.changed || providerRegisterApplied.changed) {
+    if (dryRun !== true) {
+      await writeFile(providerPath.absolutePath, providerRegisterApplied.content, "utf8");
+    }
+    touchedFiles.add(providerPath.relativePath);
+  }
+
+  let existingContainerSource = "";
+  try {
+    existingContainerSource = await readFile(containerFilePath, "utf8");
+  } catch {
+    existingContainerSource = "";
+  }
+  if (!existingContainerSource) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(containerFilePath), { recursive: true });
+      await writeFile(
+        containerFilePath,
+        renderContainerPageSource({
+          surface,
+          title: name,
+          subtitle: `Manage ${toKebabCase(name).replaceAll("-", " ")} modules.`,
+          containerHost: containerSlug,
+          sectionContainerComponentImportPath: `/${toPosixPath(path.join(componentDirectory, `${SECTION_CONTAINER_SHELL_COMPONENT}.vue`))}`
+        }),
+        "utf8"
+      );
+    }
+    touchedFiles.add(containerRelativePath);
+  }
+
+  const placementSource = await readFile(placementPath.absolutePath, "utf8");
+  const placementIdSuffix = routePath.replaceAll("/", "-");
+  const placementMarker = `jskit:ui-generator.container.menu:${surface}:${routePath}`;
+  const placementBlock =
+    `// ${placementMarker}\n` +
+    "{\n" +
+    "  addPlacement({\n" +
+    `    id: "ui-generator.container.${placementIdSuffix}.menu",\n` +
+    `    host: "${placementTarget.host}",\n` +
+    `    position: "${placementTarget.position}",\n` +
+    `    surfaces: ["${surface}"],\n` +
+    "    order: 155,\n" +
+    '    componentToken: "users.web.shell.surface-aware-menu-link-item",\n' +
+    "    props: {\n" +
+    `      label: "${name}",\n` +
+    `      surface: "${surface}",\n` +
+    `      workspaceSuffix: "/${routePath}",\n` +
+    `      nonWorkspaceSuffix: "/${routePath}"\n` +
+    "    },\n" +
+    "    when: ({ auth }) => Boolean(auth?.authenticated)\n" +
+    "  });\n" +
+    "}\n";
+  const placementApplied = appendBlockIfMarkerMissing(placementSource, placementMarker, placementBlock);
+  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:
+      touchedFileList.length > 0
+        ? `Generated UI container "${routePath}" with outlet "${containerSlug}:${CONTAINER_OUTLET_POSITION}".`
+        : `UI container "${routePath}" is already up to date.`
+  };
+}
+
+export { runGeneratorSubcommand };

package/src/server/subcommands/element.js

@@ -0,0 +1,148 @@
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import {
+  resolveShellOutletPlacementTargetFromApp,
+  toPosixPath
+} from "@jskit-ai/kernel/server/support";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  DEFAULT_COMPONENT_DIRECTORY,
+  MAIN_CLIENT_PROVIDER_FILE,
+  PLACEMENT_FILE,
+  toKebabCase,
+  toPascalCase,
+  requireOption,
+  resolvePathWithinApp,
+  appendBlockIfMarkerMissing,
+  insertImportIfMissing,
+  insertBeforeClassDeclaration
+} from "./support.js";
+
+function renderElementComponentSource(elementName = "") {
+  return `<template>
+  <section class="pa-4">
+    <h2 class="text-h6 mb-2">${elementName}</h2>
+    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your UI element implementation.</p>
+  </section>
+</template>
+`;
+}
+
+async function runGeneratorSubcommand({
+  appRoot,
+  subcommand = "",
+  args = [],
+  options = {},
+  dryRun = false
+} = {}) {
+  const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand !== "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.");
+  }
+
+  const name = requireOption(options, "name", { context: "ui-generator element" });
+  const surface = requireOption(options, "surface", { context: "ui-generator element" }).toLowerCase();
+  const componentDirectory = normalizeText(options.path) || DEFAULT_COMPONENT_DIRECTORY;
+  const elementNamePascal = toPascalCase(name);
+  const elementNameKebab = toKebabCase(name);
+
+  if (!elementNamePascal || !elementNameKebab) {
+    throw new Error("ui-generator element requires a valid --name.");
+  }
+
+  const componentPath = resolvePathWithinApp(appRoot, path.join(componentDirectory, `${elementNamePascal}Element.vue`), {
+    context: "ui-generator element"
+  });
+  const providerPath = resolvePathWithinApp(appRoot, MAIN_CLIENT_PROVIDER_FILE, {
+    context: "ui-generator element"
+  });
+  const placementPath = resolvePathWithinApp(appRoot, PLACEMENT_FILE, {
+    context: "ui-generator element"
+  });
+  const componentToken = `local.main.ui.element.${elementNameKebab}`;
+  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
+    appRoot,
+    context: "ui-generator",
+    placement: options?.placement
+  });
+
+  const touchedFiles = new Set();
+
+  let componentSource = "";
+  try {
+    componentSource = await readFile(componentPath.absolutePath, "utf8");
+  } catch {
+    componentSource = "";
+  }
+  if (!componentSource) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(componentPath.absolutePath), { recursive: true });
+      await writeFile(componentPath.absolutePath, renderElementComponentSource(name), "utf8");
+    }
+    touchedFiles.add(componentPath.relativePath);
+  }
+
+  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}.`
+    );
+  }
+
+  const componentImportLine =
+    `import ${elementNamePascal}Element from "/${toPosixPath(path.join(componentDirectory, `${elementNamePascal}Element.vue`))}";`;
+  const componentRegisterLine =
+    `registerMainClientComponent("${componentToken}", () => ${elementNamePascal}Element);`;
+
+  const providerImportApplied = insertImportIfMissing(providerSource, componentImportLine);
+  const providerRegisterApplied = insertBeforeClassDeclaration(
+    providerImportApplied.content,
+    componentRegisterLine,
+    {
+      className: "MainClientProvider",
+      contextFile: MAIN_CLIENT_PROVIDER_FILE
+    }
+  );
+  if (providerImportApplied.changed || providerRegisterApplied.changed) {
+    if (dryRun !== true) {
+      await writeFile(providerPath.absolutePath, providerRegisterApplied.content, "utf8");
+    }
+    touchedFiles.add(providerPath.relativePath);
+  }
+
+  const placementSource = await readFile(placementPath.absolutePath, "utf8");
+  const placementMarker = `jskit:ui-generator.element:${surface}:${elementNameKebab}`;
+  const placementBlock =
+    `// ${placementMarker}\n` +
+    "{\n" +
+    "  addPlacement({\n" +
+    `    id: "ui-generator.element.${elementNameKebab}",\n` +
+    `    host: "${placementTarget.host}",\n` +
+    `    position: "${placementTarget.position}",\n` +
+    `    surfaces: ["${surface}"],\n` +
+    "    order: 155,\n" +
+    `    componentToken: "${componentToken}"\n` +
+    "  });\n" +
+    "}\n";
+  const placementApplied = appendBlockIfMarkerMissing(placementSource, placementMarker, placementBlock);
+  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:
+      touchedFileList.length > 0
+        ? `Generated UI element "${elementNameKebab}" and placement token "${componentToken}".`
+        : `UI element "${elementNameKebab}" is already up to date.`
+  };
+}
+
+export { runGeneratorSubcommand };