@jskit-ai/assistant 0.1.40 → 0.1.42

package/src/server/pageSupport.js

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import {
+  resolvePageLinkTargetDetails,
+  resolvePageTargetDetails
+} from "@jskit-ai/kernel/server/support";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const PAGE_TEMPLATE_FILE = "../../templates/src/pages/assistant/index.vue";
+const SETTINGS_PAGE_TEMPLATE_FILE = "../../templates/src/pages/settings/assistant/index.vue";
+
+function resolveLinkToPropLine(linkTo = "") {
+  if (!linkTo) {
+    return "";
+  }
+  return `      to: ${JSON.stringify(linkTo)},\n`;
+}
+
+function resolveTemplateFilePath(relativePath = "") {
+  return fileURLToPath(new URL(relativePath, import.meta.url));
+}
+
+async function readAssistantPageTemplateSource(kind = "page") {
+  const templateFilePath =
+    kind === "settings-page"
+      ? resolveTemplateFilePath(SETTINGS_PAGE_TEMPLATE_FILE)
+      : resolveTemplateFilePath(PAGE_TEMPLATE_FILE);
+  return readFile(templateFilePath, "utf8");
+}
+
+function renderAssistantPageSource(templateSource = "", surfaceId = "") {
+  return String(templateSource || "").replaceAll("__ASSISTANT_SURFACE_ID__", String(surfaceId || ""));
+}
+
+async function resolveAssistantPageGenerationContext({
+  appRoot,
+  targetFile = "",
+  options = {},
+  context = "assistant page"
+} = {}) {
+  const pageTarget = await resolvePageTargetDetails({
+    appRoot,
+    targetFile,
+    context
+  });
+  const linkTarget = await resolvePageLinkTargetDetails({
+    appRoot: pageTarget.appRoot,
+    pageTarget,
+    targetFile,
+    context,
+    placement: options?.["link-placement"],
+    componentToken: options?.["link-component-token"],
+    linkTo: options?.["link-to"]
+  });
+
+  return Object.freeze({
+    pageTarget,
+    pageLabel: normalizeText(options?.name) || pageTarget.defaultName,
+    linkPlacementHost: String(linkTarget.placementTarget?.host || ""),
+    linkPlacementPosition: String(linkTarget.placementTarget?.position || ""),
+    linkComponentToken: String(linkTarget.componentToken || ""),
+    linkWorkspaceSuffix: pageTarget.routeUrlSuffix,
+    linkNonWorkspaceSuffix: pageTarget.routeUrlSuffix,
+    linkToPropLine: resolveLinkToPropLine(linkTarget.linkTo)
+  });
+}
+
+function renderAssistantPageLinkPlacementBlock({
+  marker = "",
+  pageTarget = {},
+  generationContext = {}
+} = {}) {
+  return (
+    `// ${marker}\n` +
+    "{\n" +
+    "  addPlacement({\n" +
+    `    id: "${String(pageTarget?.placementId || "")}",\n` +
+    `    host: "${String(generationContext?.linkPlacementHost || "")}",\n` +
+    `    position: "${String(generationContext?.linkPlacementPosition || "")}",\n` +
+    `    surfaces: ["${String(pageTarget?.surfaceId || "")}"],\n` +
+    "    order: 155,\n" +
+    `    componentToken: "${String(generationContext?.linkComponentToken || "")}",\n` +
+    "    props: {\n" +
+    `      label: "${String(generationContext?.pageLabel || "")}",\n` +
+    `      surface: "${String(pageTarget?.surfaceId || "")}",\n` +
+    `      workspaceSuffix: "${String(generationContext?.linkWorkspaceSuffix || "")}",\n` +
+    `      nonWorkspaceSuffix: "${String(generationContext?.linkNonWorkspaceSuffix || "")}",\n` +
+    `${String(generationContext?.linkToPropLine || "")}    },\n` +
+    "    when: ({ auth }) => Boolean(auth?.authenticated)\n" +
+    "  });\n" +
+    "}\n"
+  );
+}
+
+function renderAssistantPageSummary(
+  pageTarget = {},
+  { pageAlreadyExisted = false, pageOverwritten = false } = {}
+) {
+  if (!pageAlreadyExisted) {
+    return `Generated assistant page "${String(pageTarget?.routeUrlSuffix || "")}".`;
+  }
+  if (pageOverwritten) {
+    return `Regenerated assistant page "${String(pageTarget?.routeUrlSuffix || "")}".`;
+  }
+  return `Generated assistant page "${String(pageTarget?.routeUrlSuffix || "")}".`;
+}
+
+export {
+  readAssistantPageTemplateSource,
+  renderAssistantPageSource,
+  resolveAssistantPageGenerationContext,
+  renderAssistantPageLinkPlacementBlock,
+  renderAssistantPageSummary
+};

package/src/server/subcommands/page.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { normalizeBoolean, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  readAssistantPageTemplateSource,
+  renderAssistantPageLinkPlacementBlock,
+  renderAssistantPageSource,
+  renderAssistantPageSummary,
+  resolveAssistantPageGenerationContext
+} from "../pageSupport.js";
+import {
+  PLACEMENT_FILE,
+  appendBlockIfMarkerMissing,
+  rejectUnexpectedOptions,
+  requireEmptyPageSource,
+  requireSinglePositionalTargetFile,
+  resolvePathWithinApp
+} from "./support.js";
+
+async function runGeneratorSubcommand({
+  appRoot,
+  subcommand = "",
+  args = [],
+  options = {},
+  dryRun = false
+} = {}) {
+  const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand !== "page") {
+    throw new Error(`Unsupported assistant subcommand: ${normalizedSubcommand || "<empty>"}.`);
+  }
+
+  const targetFile = requireSinglePositionalTargetFile(args, { context: "assistant page" });
+  rejectUnexpectedOptions(options, ["name", "link-placement", "link-component-token", "link-to", "force"], {
+    context: "assistant page"
+  });
+  const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")
+    ? normalizeBoolean(options.force)
+    : false;
+
+  const generationContext = await resolveAssistantPageGenerationContext({
+    appRoot,
+    targetFile,
+    options,
+    context: "assistant page"
+  });
+  const pageTarget = generationContext.pageTarget;
+  const pageFilePath = pageTarget.targetFilePath.absolutePath;
+  const pageRelativePath = pageTarget.targetFilePath.relativePath;
+  const templateSource = await readAssistantPageTemplateSource("page");
+  const desiredPageSource = renderAssistantPageSource(templateSource, pageTarget.surfaceId);
+
+  let existingPageSource = "";
+  let pageAlreadyExisted = true;
+  try {
+    existingPageSource = await readFile(pageFilePath, "utf8");
+  } catch {
+    pageAlreadyExisted = false;
+  }
+
+  requireEmptyPageSource(existingPageSource, pageRelativePath, {
+    context: "assistant page",
+    forceOverwrite
+  });
+
+  const touchedFiles = new Set();
+  if (!pageAlreadyExisted || forceOverwrite) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(pageFilePath), { recursive: true });
+      await writeFile(pageFilePath, desiredPageSource, "utf8");
+    }
+    touchedFiles.add(pageRelativePath);
+  }
+
+  const placementPath = resolvePathWithinApp(pageTarget.appRoot, PLACEMENT_FILE, {
+    context: "assistant page"
+  });
+  const placementSource = await readFile(placementPath.absolutePath, "utf8");
+  const placementMarker = `jskit:assistant.page.link:${pageTarget.surfaceId}:${pageTarget.routeUrlSuffix}`;
+  const placementApplied = appendBlockIfMarkerMissing(
+    placementSource,
+    placementMarker,
+    renderAssistantPageLinkPlacementBlock({
+      marker: placementMarker,
+      pageTarget,
+      generationContext
+    })
+  );
+  if (placementApplied.changed) {
+    if (dryRun !== true) {
+      await writeFile(placementPath.absolutePath, placementApplied.content, "utf8");
+    }
+    touchedFiles.add(placementPath.relativePath);
+  }
+
+  return {
+    touchedFiles: [...touchedFiles].sort((left, right) => left.localeCompare(right)),
+    summary: renderAssistantPageSummary(pageTarget, {
+      pageAlreadyExisted,
+      pageOverwritten: pageAlreadyExisted && forceOverwrite
+    })
+  };
+}
+
+export { runGeneratorSubcommand };

package/src/server/subcommands/settingsPage.js

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { normalizeBoolean, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  readAssistantPageTemplateSource,
+  renderAssistantPageLinkPlacementBlock,
+  renderAssistantPageSource,
+  renderAssistantPageSummary,
+  resolveAssistantPageGenerationContext
+} from "../pageSupport.js";
+import { loadAppConfig, resolveSurfaceDefinition } from "../support.js";
+import {
+  PLACEMENT_FILE,
+  appendBlockIfMarkerMissing,
+  rejectUnexpectedOptions,
+  requireEmptyPageSource,
+  requireSinglePositionalTargetFile,
+  resolvePathWithinApp
+} from "./support.js";
+
+async function runGeneratorSubcommand({
+  appRoot,
+  subcommand = "",
+  args = [],
+  options = {},
+  dryRun = false
+} = {}) {
+  const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand !== "settings-page") {
+    throw new Error(`Unsupported assistant subcommand: ${normalizedSubcommand || "<empty>"}.`);
+  }
+
+  const targetFile = requireSinglePositionalTargetFile(args, { context: "assistant settings-page" });
+  rejectUnexpectedOptions(options, ["surface", "name", "link-placement", "link-component-token", "link-to", "force"], {
+    context: "assistant settings-page"
+  });
+  const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")
+    ? normalizeBoolean(options.force)
+    : false;
+
+  const appConfig = await loadAppConfig(appRoot);
+  const targetSurface = resolveSurfaceDefinition(appConfig, options?.surface, "surface");
+  const generationContext = await resolveAssistantPageGenerationContext({
+    appRoot,
+    targetFile,
+    options,
+    context: "assistant settings-page"
+  });
+  const pageTarget = generationContext.pageTarget;
+  const pageFilePath = pageTarget.targetFilePath.absolutePath;
+  const pageRelativePath = pageTarget.targetFilePath.relativePath;
+  const templateSource = await readAssistantPageTemplateSource("settings-page");
+  const desiredPageSource = renderAssistantPageSource(templateSource, targetSurface.id);
+
+  let existingPageSource = "";
+  let pageAlreadyExisted = true;
+  try {
+    existingPageSource = await readFile(pageFilePath, "utf8");
+  } catch {
+    pageAlreadyExisted = false;
+  }
+
+  requireEmptyPageSource(existingPageSource, pageRelativePath, {
+    context: "assistant settings-page",
+    forceOverwrite
+  });
+
+  const touchedFiles = new Set();
+  if (!pageAlreadyExisted || forceOverwrite) {
+    if (dryRun !== true) {
+      await mkdir(path.dirname(pageFilePath), { recursive: true });
+      await writeFile(pageFilePath, desiredPageSource, "utf8");
+    }
+    touchedFiles.add(pageRelativePath);
+  }
+
+  const placementPath = resolvePathWithinApp(pageTarget.appRoot, PLACEMENT_FILE, {
+    context: "assistant settings-page"
+  });
+  const placementSource = await readFile(placementPath.absolutePath, "utf8");
+  const placementMarker =
+    `jskit:assistant.settings-page.link:${pageTarget.surfaceId}:${pageTarget.routeUrlSuffix}:${targetSurface.id}`;
+  const placementApplied = appendBlockIfMarkerMissing(
+    placementSource,
+    placementMarker,
+    renderAssistantPageLinkPlacementBlock({
+      marker: placementMarker,
+      pageTarget,
+      generationContext
+    })
+  );
+  if (placementApplied.changed) {
+    if (dryRun !== true) {
+      await writeFile(placementPath.absolutePath, placementApplied.content, "utf8");
+    }
+    touchedFiles.add(placementPath.relativePath);
+  }
+
+  return {
+    touchedFiles: [...touchedFiles].sort((left, right) => left.localeCompare(right)),
+    summary: renderAssistantPageSummary(pageTarget, {
+      pageAlreadyExisted,
+      pageOverwritten: pageAlreadyExisted && forceOverwrite
+    })
+  };
+}
+
+export { runGeneratorSubcommand };

package/src/server/subcommands/support.js

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { resolveRequiredAppRoot, toPosixPath } from "@jskit-ai/kernel/server/support";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const PLACEMENT_FILE = "src/placement.js";
+
+function requireSinglePositionalTargetFile(args = [], { context = "assistant" } = {}) {
+  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 rejectUnexpectedOptions(options = {}, allowedOptionNames = [], { context = "assistant" } = {}) {
+  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 = "assistant" } = {}) {
+  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 requireEmptyPageSource(existingSource = "", targetRelativePath = "", { context = "assistant", forceOverwrite = false } = {}) {
+  const sourceText = String(existingSource || "");
+  if (!sourceText) {
+    return;
+  }
+  if (forceOverwrite) {
+    return;
+  }
+
+  throw new Error(
+    `${context} will not overwrite existing page ${targetRelativePath}. Re-run with --force to overwrite it.`
+  );
+}
+
+export {
+  PLACEMENT_FILE,
+  requireSinglePositionalTargetFile,
+  rejectUnexpectedOptions,
+  resolvePathWithinApp,
+  appendBlockIfMarkerMissing,
+  requireEmptyPageSource
+};

package/src/server/support.js

@@ -0,0 +1,78 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadAppConfigFromModuleUrl, resolveRequiredAppRoot } from "@jskit-ai/kernel/server/support";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
+
+function normalizeConfigScope(value = "") {
+  const normalized = normalizeText(value).toLowerCase();
+  if (normalized === "global" || normalized === "workspace") {
+    return normalized;
+  }
+
+  throw new Error('assistant generator option "config-scope" must be "global" or "workspace".');
+}
+
+async function loadAppConfig(appRoot = "") {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context: "assistant generator"
+  });
+  const publicConfigUrl = pathToFileURL(path.join(resolvedAppRoot, "config", "public.js")).href;
+  return loadAppConfigFromModuleUrl({
+    moduleUrl: publicConfigUrl
+  });
+}
+
+function resolveSurfaceDefinition(appConfig = {}, surfaceId = "", optionName = "surface") {
+  const normalizedSurfaceId = normalizeSurfaceId(surfaceId);
+  if (!normalizedSurfaceId) {
+    throw new Error(`assistant generator requires --${optionName}.`);
+  }
+
+  const sourceDefinitions =
+    appConfig && typeof appConfig.surfaceDefinitions === "object" && !Array.isArray(appConfig.surfaceDefinitions)
+      ? appConfig.surfaceDefinitions
+      : {};
+  const rawDefinition = sourceDefinitions[normalizedSurfaceId];
+  if (!rawDefinition || typeof rawDefinition !== "object" || Array.isArray(rawDefinition)) {
+    throw new Error(`assistant generator surface "${normalizedSurfaceId}" is not defined in config/public.js.`);
+  }
+  if (rawDefinition.enabled === false) {
+    throw new Error(`assistant generator surface "${normalizedSurfaceId}" is disabled in config/public.js.`);
+  }
+
+  return Object.freeze({
+    id: normalizedSurfaceId,
+    requiresWorkspace: rawDefinition.requiresWorkspace === true,
+    accessPolicyId: normalizeText(rawDefinition.accessPolicyId).toLowerCase()
+  });
+}
+
+function assertAssistantSurfaceIsAvailable(appConfig = {}, surfaceId = "") {
+  const assistantSurfaces =
+    appConfig && typeof appConfig.assistantSurfaces === "object" && !Array.isArray(appConfig.assistantSurfaces)
+      ? appConfig.assistantSurfaces
+      : {};
+  if (assistantSurfaces[surfaceId]) {
+    throw new Error(`assistant generator surface "${surfaceId}" already has an assistant configured in config/public.js.`);
+  }
+}
+
+function resolveAiConfigPrefix(surfaceId = "", explicitPrefix = "") {
+  const normalizedExplicitPrefix = normalizeText(explicitPrefix);
+  if (normalizedExplicitPrefix) {
+    return normalizedExplicitPrefix;
+  }
+
+  const surfacePrefix = toSnakeCase(surfaceId).toUpperCase();
+  return surfacePrefix ? `${surfacePrefix}_ASSISTANT` : "ASSISTANT";
+}
+
+export {
+  normalizeConfigScope,
+  loadAppConfig,
+  resolveSurfaceDefinition,
+  assertAssistantSurfaceIsAvailable,
+  resolveAiConfigPrefix
+};

package/test/buildTemplateContext.test.js

@@ -9,7 +9,6 @@ async function withTempApp(run) {
   const appRoot = await mkdtemp(path.join(tmpdir(), "assistant-generator-"));
   try {
     await mkdir(path.join(appRoot, "config"), { recursive: true });
-    await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
     await writeFile(
       path.join(appRoot, "package.json"),
       `${JSON.stringify({ name: "assistant-generator-test-app", private: true, type: "module" }, null, 2)}\n`,
@@ -25,17 +24,6 @@ async function withTempApp(run) {
   },
   assistantSurfaces: {}
 };
-`,
-      "utf8"
-    );
-    await writeFile(
-      path.join(appRoot, "src", "components", "ShellLayout.vue"),
-      `<template>
-  <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" />
-    <ShellOutlet host="shell-layout" position="top-right" default />
-  </div>
-</template>
 `,
       "utf8"
     );
@@ -46,29 +34,36 @@ async function withTempApp(run) {
   }
 }
 
-test("buildTemplateContext derives per-surface placeholders from explicit surfaces", async () => {
+test("buildTemplateContext derives assistant setup placeholders from explicit setup surfaces", async () => {
   await withTempApp(async (appRoot) => {
     const context = await buildTemplateContext({
       appRoot,
       options: {
         surface: "app",
         "settings-surface": "console",
-        "config-scope": "global",
-        placement: "shell-layout:primary-menu",
-        "menu-label": "Copilot"
+        "config-scope": "global"
       }
     });
 
-    assert.equal(context.__ASSISTANT_SURFACE_ID__, "app");
     assert.equal(context.__ASSISTANT_SETTINGS_SURFACE_ID__, "console");
     assert.equal(context.__ASSISTANT_CONFIG_SCOPE__, "global");
-    assert.equal(context.__ASSISTANT_SETTINGS_HOST__, "console-settings");
     assert.equal(context.__ASSISTANT_AI_CONFIG_PREFIX__, "APP_ASSISTANT");
-    assert.equal(context.__ASSISTANT_MENU_PLACEMENT_HOST__, "shell-layout");
-    assert.equal(context.__ASSISTANT_MENU_PLACEMENT_POSITION__, "primary-menu");
-    assert.equal(context.__ASSISTANT_MENU_LABEL__, "Copilot");
-    assert.equal(context.__ASSISTANT_SETTINGS_MENU_WORKSPACE_SUFFIX__, "/settings/assistant");
-    assert.equal(context.__ASSISTANT_SETTINGS_MENU_NON_WORKSPACE_SUFFIX__, "/settings/assistant");
+  });
+});
+
+test("buildTemplateContext honors explicit AI config prefix overrides", async () => {
+  await withTempApp(async (appRoot) => {
+    const context = await buildTemplateContext({
+      appRoot,
+      options: {
+        surface: "app",
+        "settings-surface": "console",
+        "config-scope": "global",
+        "ai-config-prefix": "CUSTOM_ASSISTANT"
+      }
+    });
+
+    assert.equal(context.__ASSISTANT_AI_CONFIG_PREFIX__, "CUSTOM_ASSISTANT");
   });
 });
 
@@ -81,8 +76,7 @@ test("buildTemplateContext rejects workspace config scope for a non-workspace as
           options: {
             surface: "app",
             "settings-surface": "console",
-            "config-scope": "workspace",
-            placement: "shell-layout:primary-menu"
+            "config-scope": "workspace"
           }
         }),
       /config-scope "workspace" requires surface "app" with requiresWorkspace=true/
@@ -117,8 +111,7 @@ test("buildTemplateContext rejects duplicate assistant surfaces already configur
           options: {
             surface: "app",
             "settings-surface": "console",
-            "config-scope": "global",
-            placement: "shell-layout:primary-menu"
+            "config-scope": "global"
           }
         }),
       /already has an assistant configured/