@jskit-ai/assistant 0.1.40 → 0.1.41

package/README.md

@@ -0,0 +1,91 @@
+# @jskit-ai/assistant
+
+Install assistant runtime/config for one surface, then scaffold assistant pages at explicit page files.
+
+## Mental Model
+
+`@jskit-ai/assistant` is the generator package.
+
+- `setup` installs the assistant runtime/config/env wiring.
+- `page <target-file>` creates the assistant runtime page anywhere relative to `src/pages/...`.
+- `settings-page <target-file>` creates the assistant settings page anywhere relative to `src/pages/...`.
+
+There is no separate server command and no separate client command.
+
+The layering is:
+
+- `@jskit-ai/assistant`: generator package with `setup`, `page`, and `settings-page`
+- `@jskit-ai/assistant-runtime`: runtime package installed by `setup`
+- `@jskit-ai/assistant-core`: lower-level provider/client library pulled in by `assistant-runtime`
+
+So the normal flow is:
+
+- run `setup`
+- optionally create `page`
+- optionally create `settings-page`
+
+Page placement follows the same file-driven model as `@jskit-ai/ui-generator`.
+
+- The surface comes from where the page file lives.
+- The route URL comes from that file path.
+- The default page-link placement comes from the nearest real parent subpages host when there is one.
+
+Only one assistant can be installed per target surface. That rule is enforced by `setup`, which writes the per-surface config entries.
+
+## Setup
+
+```bash
+npx jskit generate @jskit-ai/assistant setup \
+  --surface admin \
+  --settings-surface console \
+  --config-scope global \
+  --ai-provider openai \
+  --ai-api-key "$OPENAI_API_KEY" \
+  --ai-base-url "" \
+  --ai-timeout-ms 120000
+```
+
+`setup` does not create pages.
+
+It only registers:
+
+- `config.assistantSurfaces.<surface>`
+- `config.assistantServer.<surface>`
+- prefixed AI env defaults in `.env`
+- the `@jskit-ai/assistant-runtime` dependency chain, including `@jskit-ai/assistant-core`
+
+## Runtime Page
+
+```bash
+npx jskit generate @jskit-ai/assistant page \
+  admin/ops/copilot/index.vue
+```
+
+The page surface id comes from the target file path.
+
+Optional page-link overrides:
+
+- `--name`
+- `--link-placement`
+- `--link-component-token`
+- `--link-to`
+
+## Settings Page
+
+```bash
+npx jskit generate @jskit-ai/assistant settings-page \
+  admin/settings/index/assistant/index.vue \
+  --surface admin
+```
+
+For `settings-page`, the page location and the assistant target surface are separate concerns:
+
+- `<target-file>` decides where the settings page lives and how its page link is placed
+- `--surface` decides which assistant surface the settings page edits
+
+The same optional page-link overrides are supported:
+
+- `--name`
+- `--link-placement`
+- `--link-component-token`
+- `--link-to`

package/package.descriptor.mjs

@@ -1,58 +1,70 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/assistant",
-  version: "0.1.40",
+  version: "0.1.41",
   kind: "generator",
-  description: "Generate an assistant page and per-surface assistant config using the shared assistant runtime.",
+  description: "Install assistant runtime/config for one surface and scaffold assistant pages at explicit target files.",
   options: {
     surface: {
       required: true,
       inputType: "text",
+      validationType: "enabled-surface-id",
       defaultFromConfig: "surfaceDefaultId",
       promptLabel: "Assistant surface",
-      promptHint: "Enabled surface id where the assistant page will run."
+      promptHint: "Assistant runtime surface id. Used by setup, or selected assistant surface for settings-page.",
+      helpHint: "For setup, this is the runtime surface receiving assistant wiring. For settings-page, this is the assistant runtime configured by that page."
     },
     "settings-surface": {
       required: true,
       inputType: "text",
+      validationType: "enabled-surface-id",
       defaultValue: "",
       promptLabel: "Settings surface",
-      promptHint: "Enabled surface id whose settings pages will include the assistant settings section."
-    },
-    "settings-route-path": {
-      required: false,
-      inputType: "text",
-      defaultValue: "assistant",
-      promptLabel: "Settings route path",
-      promptHint: "Route segment to use for the assistant settings section page."
+      promptHint: "Enabled settings host surface id used by assistant setup.",
+      helpHint: "Surface that hosts the settings UI for the selected assistant runtime."
     },
     "config-scope": {
       required: true,
       inputType: "text",
       defaultValue: "global",
       promptLabel: "Config scope",
-      promptHint: "global | workspace. Workspace scope requires both selected surfaces to requireWorkspace=true."
+      promptHint: "global | workspace. Workspace scope requires both setup surfaces to requireWorkspace=true."
     },
-    placement: {
+    name: {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Menu placement",
-      promptHint: "Optional host:position target for the assistant page menu entry."
+      promptLabel: "Page label",
+      promptHint: "Optional page link label override for page and settings-page.",
+      helpLabel: "Display label"
+    },
+    force: {
+      required: false,
+      inputType: "flag",
+      defaultValue: "",
+      promptLabel: "Force overwrite",
+      promptHint: "Overwrite the generated page file if it already exists."
     },
-    "placement-component-token": {
+    "link-placement": {
       required: false,
       inputType: "text",
-      defaultValue: "users.web.shell.surface-aware-menu-link-item",
-      promptLabel: "Placement component token",
-      promptHint: "Menu placement component token for the assistant page entry."
+      defaultValue: "",
+      promptLabel: "Link placement",
+      promptHint: "Optional host:position target for the generated page link placement."
     },
-    "menu-label": {
+    "link-component-token": {
       required: false,
       inputType: "text",
-      defaultValue: "Assistant",
-      promptLabel: "Menu label",
-      promptHint: "Menu label for the assistant page entry."
+      defaultValue: "",
+      promptLabel: "Link component token",
+      promptHint: "Optional component token override for the generated page link placement."
+    },
+    "link-to": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Link to",
+      promptHint: "Optional explicit props.to value for the generated page link placement."
     },
     "ai-config-prefix": {
       required: false,
@@ -102,11 +114,131 @@ export default Object.freeze({
     }
   },
   metadata: {
+    generatorPrimarySubcommand: "setup",
+    generatorSubcommands: {
+      setup: {
+        description: "Install assistant runtime/config for one target surface without creating pages.",
+        optionNames: [
+          "surface",
+          "settings-surface",
+          "config-scope",
+          "ai-config-prefix",
+          "ai-provider",
+          "ai-api-key",
+          "ai-base-url",
+          "ai-timeout-ms"
+        ],
+        notes: [
+          "setup installs runtime/config only. It does not create assistant pages.",
+          "--surface selects the assistant runtime surface, and --settings-surface selects the surface that will host its settings UI."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate assistant setup \\",
+              "  --surface admin \\",
+              "  --settings-surface admin \\",
+              "  --config-scope workspace \\",
+              "  --ai-api-key \"$OPENAI_API_KEY\""
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate assistant setup \\",
+              "  --surface console \\",
+              "  --settings-surface console \\",
+              "  --config-scope global \\",
+              "  --ai-config-prefix CONSOLE_ASSISTANT \\",
+              "  --ai-provider openai \\",
+              "  --ai-api-key \"$OPENAI_API_KEY\" \\",
+              "  --ai-base-url \"http://localhost:11434/v1\" \\",
+              "  --ai-timeout-ms 60000"
+            ]
+          }
+        ]
+      },
+      page: {
+        entrypoint: "src/server/subcommands/page.js",
+        export: "runGeneratorSubcommand",
+        description: "Create an assistant runtime page at an explicit target file relative to src/pages/.",
+        positionalArgs: [
+          {
+            name: "target-file",
+            required: true,
+            descriptionKey: "page-target-file"
+          }
+        ],
+        optionNames: ["name", "link-placement", "link-component-token", "link-to", "force"],
+        notes: [
+          "The target file decides where the page lives.",
+          "Page-link placement follows the same inference rules as ui-generator page.",
+          "If the target page file already exists, rerun with --force to overwrite it."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate assistant page \\",
+              "  admin/assistant/index.vue"
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate assistant page \\",
+              "  admin/ops/copilot/index.vue \\",
+              "  --name \"Copilot\" \\",
+              "  --link-placement shell-layout:top-right"
+            ]
+          }
+        ]
+      },
+      "settings-page": {
+        entrypoint: "src/server/subcommands/settingsPage.js",
+        export: "runGeneratorSubcommand",
+        description: "Create an assistant settings page at an explicit target file relative to src/pages/.",
+        positionalArgs: [
+          {
+            name: "target-file",
+            required: true,
+            descriptionKey: "page-target-file"
+          }
+        ],
+        optionNames: ["surface", "name", "link-placement", "link-component-token", "link-to", "force"],
+        requiredOptionNames: ["surface"],
+        notes: [
+          "The target file decides where the settings page lives.",
+          "--surface selects the assistant runtime being configured. It does not place the file.",
+          "If the target page file already exists, rerun with --force to overwrite it."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate assistant settings-page \\",
+              "  admin/settings/index/assistant/index.vue \\",
+              "  --surface admin"
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate assistant settings-page \\",
+              "  admin/settings/index/app-assistant/index.vue \\",
+              "  --surface app \\",
+              "  --name \"App Assistant\""
+            ]
+          }
+        ]
+      }
+    },
     apiSummary: {
       surfaces: [
         {
           subpath: "./server/buildTemplateContext",
-          summary: "Builds deterministic assistant generator template context values from app surface metadata."
+          summary: "Builds deterministic assistant setup template context values from app surface metadata."
         }
       ],
       containerTokens: {
@@ -124,83 +256,8 @@ export default Object.freeze({
       scripts: {}
     },
     procfile: {},
-    files: [
-      {
-        from: "templates/src/pages/assistant/index.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath: "assistant/index.vue",
-        reason: "Install generated assistant runtime page.",
-        category: "assistant",
-        id: "assistant-page-runtime",
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildTemplateContext"
-        }
-      },
-      {
-        from: "templates/src/pages/settings/assistant/index.vue",
-        toSurface: "${option:settings-surface|lower}",
-        toSurfacePath: "settings/${option:settings-route-path|path}/index.vue",
-        reason: "Install generated assistant settings section page.",
-        category: "assistant",
-        id: "assistant-page-settings-standard",
-        when: {
-          option: "settings-surface",
-          notEquals: "admin"
-        },
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildTemplateContext"
-        }
-      },
-      {
-        from: "templates/src/pages/settings/assistant/index.vue",
-        toSurface: "${option:settings-surface|lower}",
-        toSurfacePath: "workspace/settings/${option:settings-route-path|path}/index.vue",
-        reason: "Install generated assistant settings section page.",
-        category: "assistant",
-        id: "assistant-page-settings-admin",
-        when: {
-          option: "settings-surface",
-          equals: "admin"
-        },
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildTemplateContext"
-        }
-      }
-    ],
+    files: [],
     text: [
-      {
-        op: "append-text",
-        file: "src/placement.js",
-        position: "bottom",
-        skipIfContains: "assistant.generated.menu:${option:surface|lower}",
-        value:
-          "\n// assistant.generated.menu:${option:surface|lower}\naddPlacement({\n  id: \"assistant.generated.menu.${option:surface|kebab}\",\n  host: \"__ASSISTANT_MENU_PLACEMENT_HOST__\",\n  position: \"__ASSISTANT_MENU_PLACEMENT_POSITION__\",\n  surfaces: [\"${option:surface|lower}\"],\n  order: 310,\n  componentToken: \"__ASSISTANT_MENU_COMPONENT_TOKEN__\",\n  props: {\n    label: \"__ASSISTANT_MENU_LABEL__\",\n    surface: \"${option:surface|lower}\",\n    workspaceSuffix: \"__ASSISTANT_MENU_WORKSPACE_SUFFIX__\",\n    nonWorkspaceSuffix: \"__ASSISTANT_MENU_NON_WORKSPACE_SUFFIX__\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
-        reason: "Append generated assistant runtime menu placement into app-owned placement registry.",
-        category: "assistant",
-        id: "assistant-placement-menu",
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildTemplateContext"
-        }
-      },
-      {
-        op: "append-text",
-        file: "src/placement.js",
-        position: "bottom",
-        skipIfContains: "assistant.generated.settings.menu:${option:surface|lower}",
-        value:
-          "\n// assistant.generated.settings.menu:${option:surface|lower}\naddPlacement({\n  id: \"assistant.generated.settings.menu.${option:surface|kebab}\",\n  host: \"__ASSISTANT_SETTINGS_HOST__\",\n  position: \"primary-menu\",\n  surfaces: [\"${option:settings-surface|lower}\"],\n  order: 250,\n  componentToken: \"users.web.shell.surface-aware-menu-link-item\",\n  props: {\n    label: \"__ASSISTANT_SETTINGS_MENU_LABEL__\",\n    surface: \"${option:settings-surface|lower}\",\n    workspaceSuffix: \"__ASSISTANT_SETTINGS_MENU_WORKSPACE_SUFFIX__\",\n    nonWorkspaceSuffix: \"__ASSISTANT_SETTINGS_MENU_NON_WORKSPACE_SUFFIX__\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
-        reason: "Append generated assistant settings section menu placement into app-owned settings placements.",
-        category: "assistant",
-        id: "assistant-settings-menu-placement",
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildTemplateContext"
-        }
-      },
       {
         op: "append-text",
         file: "config/public.js",
@@ -208,7 +265,7 @@ export default Object.freeze({
         skipIfContains: "config.assistantSurfaces.${option:surface|lower} = {",
         value:
           "\nconfig.assistantSurfaces.${option:surface|lower} = {\n  settingsSurfaceId: \"__ASSISTANT_SETTINGS_SURFACE_ID__\",\n  configScope: \"__ASSISTANT_CONFIG_SCOPE__\"\n};\n",
-        reason: "Register the generated assistant surface in public app config.",
+        reason: "Register the assistant runtime surface in public app config.",
         category: "assistant",
         id: "assistant-public-surface-config",
         templateContext: {
@@ -223,7 +280,7 @@ export default Object.freeze({
         skipIfContains: "config.assistantServer.${option:surface|lower} = {",
         value:
           "\nconfig.assistantServer.${option:surface|lower} = {\n  aiConfigPrefix: \"__ASSISTANT_AI_CONFIG_PREFIX__\"\n};\n",
-        reason: "Register generated assistant server config for the selected surface.",
+        reason: "Register assistant server config for the selected runtime surface.",
         category: "assistant",
         id: "assistant-server-surface-config",
         templateContext: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -9,6 +9,6 @@
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.31"
+    "@jskit-ai/kernel": "0.1.32"
   }
 }

package/src/server/buildTemplateContext.js

@@ -1,97 +1,16 @@
-import path from "node:path";
-import { pathToFileURL } from "node:url";
 import {
-  loadAppConfigFromModuleUrl,
-  resolveShellOutletPlacementTargetFromApp
-} 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";
-
-const DEFAULT_MENU_COMPONENT_TOKEN = "users.web.shell.surface-aware-menu-link-item";
-
-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 publicConfigUrl = pathToFileURL(path.join(appRoot, "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";
-}
-
-function normalizeSettingsRoutePath(value = "") {
-  return normalizeText(value).toLowerCase().replace(/^\/+|\/+$/g, "") || "assistant";
-}
-
-function resolveSettingsRouteBase(surfaceId = "") {
-  return normalizeSurfaceId(surfaceId) === "admin" ? "/workspace/settings" : "/settings";
-}
-
-async function resolveMenuPlacementTarget(appRoot = "", options = {}) {
-  return resolveShellOutletPlacementTargetFromApp({
-    appRoot,
-    context: "assistant-generator",
-    placement: normalizeText(options?.placement)
-  });
-}
+  assertAssistantSurfaceIsAvailable,
+  loadAppConfig,
+  normalizeConfigScope,
+  resolveAiConfigPrefix,
+  resolveSurfaceDefinition
+} from "./support.js";
 
 async function buildTemplateContext({ appRoot, options } = {}) {
   const appConfig = await loadAppConfig(appRoot);
   const runtimeSurface = resolveSurfaceDefinition(appConfig, options?.surface, "surface");
   const settingsSurface = resolveSurfaceDefinition(appConfig, options?.["settings-surface"], "settings-surface");
   const configScope = normalizeConfigScope(options?.["config-scope"]);
-  const settingsRoutePath = normalizeSettingsRoutePath(options?.["settings-route-path"]);
 
   assertAssistantSurfaceIsAvailable(appConfig, runtimeSurface.id);
 
@@ -106,26 +25,10 @@ async function buildTemplateContext({ appRoot, options } = {}) {
     );
   }
 
-  const placementTarget = await resolveMenuPlacementTarget(appRoot, options);
-  const menuComponentToken = normalizeText(options?.["placement-component-token"]) || DEFAULT_MENU_COMPONENT_TOKEN;
-  const settingsRouteBase = resolveSettingsRouteBase(settingsSurface.id);
-  const settingsMenuSuffix = `${settingsRouteBase}/${settingsRoutePath}`;
-
   return Object.freeze({
-    "__ASSISTANT_SURFACE_ID__": runtimeSurface.id,
     "__ASSISTANT_SETTINGS_SURFACE_ID__": settingsSurface.id,
     "__ASSISTANT_CONFIG_SCOPE__": configScope,
-    "__ASSISTANT_SETTINGS_HOST__": `${settingsSurface.id}-settings`,
-    "__ASSISTANT_AI_CONFIG_PREFIX__": resolveAiConfigPrefix(runtimeSurface.id, options?.["ai-config-prefix"]),
-    "__ASSISTANT_MENU_PLACEMENT_HOST__": placementTarget.host,
-    "__ASSISTANT_MENU_PLACEMENT_POSITION__": placementTarget.position,
-    "__ASSISTANT_MENU_COMPONENT_TOKEN__": menuComponentToken,
-    "__ASSISTANT_MENU_LABEL__": normalizeText(options?.["menu-label"]) || "Assistant",
-    "__ASSISTANT_MENU_WORKSPACE_SUFFIX__": "/assistant",
-    "__ASSISTANT_MENU_NON_WORKSPACE_SUFFIX__": "/assistant",
-    "__ASSISTANT_SETTINGS_MENU_LABEL__": normalizeText(options?.["menu-label"]) || "Assistant",
-    "__ASSISTANT_SETTINGS_MENU_WORKSPACE_SUFFIX__": settingsMenuSuffix,
-    "__ASSISTANT_SETTINGS_MENU_NON_WORKSPACE_SUFFIX__": settingsMenuSuffix
+    "__ASSISTANT_AI_CONFIG_PREFIX__": resolveAiConfigPrefix(runtimeSurface.id, options?.["ai-config-prefix"])
   });
 }