@jskit-ai/assistant 0.1.41 → 0.1.43

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/assistant",
-  version: "0.1.41",
+  version: "0.1.43",
   kind: "generator",
   description: "Install assistant runtime/config for one surface and scaffold assistant pages at explicit target files.",
   options: {
@@ -19,8 +19,7 @@ export default Object.freeze({
       inputType: "text",
       validationType: "enabled-surface-id",
       defaultValue: "",
-      promptLabel: "Settings surface",
-      promptHint: "Enabled settings host surface id used by assistant setup.",
+      promptLabel: "Which enabled surface should host the assistant settings UI?",
       helpHint: "Surface that hosts the settings UI for the selected assistant runtime."
     },
     "config-scope": {
@@ -50,7 +49,7 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Link placement",
-      promptHint: "Optional host:position target for the generated page link placement."
+      promptHint: "Optional target for the generated page link placement (format: host:position)."
     },
     "link-component-token": {
       required: false,
@@ -69,7 +68,7 @@ export default Object.freeze({
     "ai-config-prefix": {
       required: false,
       inputType: "text",
-      defaultValue: "",
+      defaultFromOptionTemplate: "${option:surface|snake|upper}_ASSISTANT",
       promptLabel: "AI config prefix",
       promptHint: "Optional env/config prefix override. Defaults to <SURFACE>_ASSISTANT."
     },
@@ -87,8 +86,7 @@ export default Object.freeze({
       promptHint: "Leave empty to keep the assistant disabled until you add a key."
     },
     "ai-base-url": {
-      required: true,
-      allowEmpty: true,
+      required: false,
       defaultValue: "",
       promptLabel: "AI base URL",
       promptHint: "Optional provider-compatible base URL override."
@@ -160,6 +158,7 @@ export default Object.freeze({
         ]
       },
       page: {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/page.js",
         export: "runGeneratorSubcommand",
         description: "Create an assistant runtime page at an explicit target file relative to src/pages/.",
@@ -196,6 +195,7 @@ export default Object.freeze({
         ]
       },
       "settings-page": {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/settingsPage.js",
         export: "runGeneratorSubcommand",
         description: "Create an assistant settings page at an explicit target file relative to src/pages/.",
@@ -289,19 +289,40 @@ export default Object.freeze({
         }
       },
       {
-        op: "append-text",
         file: ".env",
-        position: "bottom",
-        skipIfContains: "__ASSISTANT_AI_CONFIG_PREFIX___AI_PROVIDER=",
-        value:
-          "\n__ASSISTANT_AI_CONFIG_PREFIX___AI_PROVIDER=${option:ai-provider}\n__ASSISTANT_AI_CONFIG_PREFIX___AI_API_KEY=${option:ai-api-key}\n__ASSISTANT_AI_CONFIG_PREFIX___AI_BASE_URL=${option:ai-base-url}\n__ASSISTANT_AI_CONFIG_PREFIX___AI_TIMEOUT_MS=${option:ai-timeout-ms}\n",
-        reason: "Append assistant AI env defaults for the generated surface prefix.",
+        op: "upsert-env",
+        key: "${option:ai-config-prefix}_AI_PROVIDER",
+        value: "${option:ai-provider}",
+        reason: "Configure the assistant AI provider for the selected surface.",
         category: "runtime-config",
-        id: "assistant-ai-prefixed-env",
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildTemplateContext"
-        }
+        id: "assistant-ai-provider"
+      },
+      {
+        file: ".env",
+        op: "upsert-env",
+        key: "${option:ai-config-prefix}_AI_API_KEY",
+        value: "${option:ai-api-key}",
+        reason: "Configure the assistant AI API key for the selected surface.",
+        category: "runtime-config",
+        id: "assistant-ai-api-key"
+      },
+      {
+        file: ".env",
+        op: "upsert-env",
+        key: "${option:ai-config-prefix}_AI_BASE_URL",
+        value: "${option:ai-base-url}",
+        reason: "Configure the optional assistant AI base URL override for the selected surface.",
+        category: "runtime-config",
+        id: "assistant-ai-base-url"
+      },
+      {
+        file: ".env",
+        op: "upsert-env",
+        key: "${option:ai-config-prefix}_AI_TIMEOUT_MS",
+        value: "${option:ai-timeout-ms}",
+        reason: "Configure the assistant AI timeout for the selected surface.",
+        category: "runtime-config",
+        id: "assistant-ai-timeout-ms"
       }
     ]
   }

package/package.json

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

package/src/server/pageSupport.js

@@ -56,11 +56,11 @@ async function resolveAssistantPageGenerationContext({
   return Object.freeze({
     pageTarget,
     pageLabel: normalizeText(options?.name) || pageTarget.defaultName,
-    linkPlacementHost: String(linkTarget.placementTarget?.host || ""),
-    linkPlacementPosition: String(linkTarget.placementTarget?.position || ""),
+    linkPlacementTarget: String(linkTarget.placementTarget?.id || ""),
     linkComponentToken: String(linkTarget.componentToken || ""),
     linkWorkspaceSuffix: pageTarget.routeUrlSuffix,
     linkNonWorkspaceSuffix: pageTarget.routeUrlSuffix,
+    linkWhenLine: String(linkTarget.whenLine || ""),
     linkToPropLine: resolveLinkToPropLine(linkTarget.linkTo)
   });
 }
@@ -75,8 +75,7 @@ function renderAssistantPageLinkPlacementBlock({
     "{\n" +
     "  addPlacement({\n" +
     `    id: "${String(pageTarget?.placementId || "")}",\n` +
-    `    host: "${String(generationContext?.linkPlacementHost || "")}",\n` +
-    `    position: "${String(generationContext?.linkPlacementPosition || "")}",\n` +
+    `    target: "${String(generationContext?.linkPlacementTarget || "")}",\n` +
     `    surfaces: ["${String(pageTarget?.surfaceId || "")}"],\n` +
     "    order: 155,\n" +
     `    componentToken: "${String(generationContext?.linkComponentToken || "")}",\n` +
@@ -86,7 +85,7 @@ function renderAssistantPageLinkPlacementBlock({
     `      workspaceSuffix: "${String(generationContext?.linkWorkspaceSuffix || "")}",\n` +
     `      nonWorkspaceSuffix: "${String(generationContext?.linkNonWorkspaceSuffix || "")}",\n` +
     `${String(generationContext?.linkToPropLine || "")}    },\n` +
-    "    when: ({ auth }) => Boolean(auth?.authenticated)\n" +
+    `${String(generationContext?.linkWhenLine || "")}` +
     "  });\n" +
     "}\n"
   );
@@ -94,7 +93,7 @@ function renderAssistantPageLinkPlacementBlock({
 
 function renderAssistantPageSummary(
   pageTarget = {},
-  { pageAlreadyExisted = false, pageOverwritten = false, placementChanged = false } = {}
+  { pageAlreadyExisted = false, pageOverwritten = false } = {}
 ) {
   if (!pageAlreadyExisted) {
     return `Generated assistant page "${String(pageTarget?.routeUrlSuffix || "")}".`;
@@ -102,10 +101,7 @@ function renderAssistantPageSummary(
   if (pageOverwritten) {
     return `Regenerated assistant page "${String(pageTarget?.routeUrlSuffix || "")}".`;
   }
-  if (placementChanged) {
-    return `Updated assistant page link placement for "${String(pageTarget?.routeUrlSuffix || "")}".`;
-  }
-  return `Assistant page "${String(pageTarget?.routeUrlSuffix || "")}" is already up to date.`;
+  return `Generated assistant page "${String(pageTarget?.routeUrlSuffix || "")}".`;
 }
 
 export {

package/src/server/subcommands/page.js

@@ -96,8 +96,7 @@ async function runGeneratorSubcommand({
     touchedFiles: [...touchedFiles].sort((left, right) => left.localeCompare(right)),
     summary: renderAssistantPageSummary(pageTarget, {
       pageAlreadyExisted,
-      pageOverwritten: pageAlreadyExisted && forceOverwrite,
-      placementChanged: placementApplied.changed
+      pageOverwritten: pageAlreadyExisted && forceOverwrite
     })
   };
 }

package/src/server/subcommands/settingsPage.js

@@ -100,8 +100,7 @@ async function runGeneratorSubcommand({
     touchedFiles: [...touchedFiles].sort((left, right) => left.localeCompare(right)),
     summary: renderAssistantPageSummary(pageTarget, {
       pageAlreadyExisted,
-      pageOverwritten: pageAlreadyExisted && forceOverwrite,
-      placementChanged: placementApplied.changed
+      pageOverwritten: pageAlreadyExisted && forceOverwrite
     })
   };
 }

package/test/packageDescriptor.test.js

@@ -15,8 +15,13 @@ test("assistant descriptor exposes setup as the primary command and still depend
   assert.equal(descriptor.options?.["settings-surface"]?.required, true);
   assert.equal(descriptor.options?.["settings-surface"]?.validationType, "enabled-surface-id");
   assert.equal(descriptor.options?.["config-scope"]?.defaultValue, "global");
+  assert.equal(
+    descriptor.options?.["ai-config-prefix"]?.defaultFromOptionTemplate,
+    "${option:surface|snake|upper}_ASSISTANT"
+  );
   assert.equal(descriptor.options?.name?.required, false);
   assert.equal(descriptor.options?.["link-placement"]?.required, false);
+  assert.equal(descriptor.options?.["ai-base-url"]?.required, false);
   assert.deepEqual(descriptor.dependsOn, ["@jskit-ai/assistant-runtime"]);
 });
 
@@ -34,16 +39,30 @@ test("assistant descriptor defines explicit page subcommands and setup-only muta
   assert.equal(fileMutations.length, 0);
 });
 
-test("assistant descriptor appends only setup config and env entries", () => {
+test("assistant descriptor appends setup config and upserts assistant env entries", () => {
   const publicConfig = findTextMutation("assistant-public-surface-config");
   const serverConfig = findTextMutation("assistant-server-surface-config");
-  const envBlock = findTextMutation("assistant-ai-prefixed-env");
+  const envProvider = findTextMutation("assistant-ai-provider");
+  const envApiKey = findTextMutation("assistant-ai-api-key");
+  const envBaseUrl = findTextMutation("assistant-ai-base-url");
+  const envTimeout = findTextMutation("assistant-ai-timeout-ms");
   const textMutations = Array.isArray(descriptor?.mutations?.text) ? descriptor.mutations.text : [];
 
-  assert.equal(textMutations.length, 3);
+  assert.equal(textMutations.length, 6);
   assert.match(String(publicConfig?.value || ""), /config\.assistantSurfaces\.\$\{option:surface\|lower\} = \{/);
   assert.match(String(publicConfig?.value || ""), /settingsSurfaceId: "__ASSISTANT_SETTINGS_SURFACE_ID__"/);
   assert.match(String(serverConfig?.value || ""), /config\.assistantServer\.\$\{option:surface\|lower\} = \{/);
   assert.match(String(serverConfig?.value || ""), /aiConfigPrefix: "__ASSISTANT_AI_CONFIG_PREFIX__"/);
-  assert.match(String(envBlock?.value || ""), /__ASSISTANT_AI_CONFIG_PREFIX___AI_PROVIDER=\$\{option:ai-provider\}/);
+  assert.equal(envProvider?.op, "upsert-env");
+  assert.equal(envProvider?.key, "${option:ai-config-prefix}_AI_PROVIDER");
+  assert.equal(envProvider?.value, "${option:ai-provider}");
+  assert.equal(envApiKey?.op, "upsert-env");
+  assert.equal(envApiKey?.key, "${option:ai-config-prefix}_AI_API_KEY");
+  assert.equal(envApiKey?.value, "${option:ai-api-key}");
+  assert.equal(envBaseUrl?.op, "upsert-env");
+  assert.equal(envBaseUrl?.key, "${option:ai-config-prefix}_AI_BASE_URL");
+  assert.equal(envBaseUrl?.value, "${option:ai-base-url}");
+  assert.equal(envTimeout?.op, "upsert-env");
+  assert.equal(envTimeout?.key, "${option:ai-config-prefix}_AI_TIMEOUT_MS");
+  assert.equal(envTimeout?.value, "${option:ai-timeout-ms}");
 });

package/test/subcommands.test.js

@@ -25,11 +25,12 @@ function toPagePath(targetFile = "") {
   return path.join("src/pages", targetFile);
 }
 
-async function writeAppFixture(appRoot) {
+async function writeAppFixture(appRoot, { configSource = "" } = {}) {
   await writeFileInApp(
     appRoot,
     "config/public.js",
-    `export const config = {
+    configSource ||
+      `export const config = {
   surfaceDefinitions: {
     admin: {
       id: "admin",
@@ -55,8 +56,8 @@ async function writeAppFixture(appRoot) {
     "src/components/ShellLayout.vue",
     `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
-    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet target="shell-layout:primary-menu" default />
+    <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
 `
@@ -87,6 +88,7 @@ test("assistant page subcommand creates a runtime page at an explicit target fil
     });
 
     assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+    assert.equal(result.summary, 'Generated assistant page "/ops/copilot".');
 
     const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
     assert.match(pageSource, /<AssistantSurfaceClientElement surface-id="admin" \/>/);
@@ -94,8 +96,7 @@ test("assistant page subcommand creates a runtime page at an explicit target fil
     const placementSource = await readFile(path.join(appRoot, "src/placement.js"), "utf8");
     assert.match(placementSource, /jskit:assistant\.page\.link:admin:\/ops\/copilot/);
     assert.match(placementSource, /id: "ui-generator\.page\.admin\.ops\.copilot\.link"/);
-    assert.match(placementSource, /host: "shell-layout"/);
-    assert.match(placementSource, /position: "primary-menu"/);
+    assert.match(placementSource, /target: "shell-layout:primary-menu"/);
     assert.match(placementSource, /label: "Copilot"/);
     assert.match(placementSource, /workspaceSuffix: "\/ops\/copilot"/);
   });
@@ -110,7 +111,7 @@ test("assistant settings-page subcommand uses the target assistant surface and i
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="admin-settings" position="sub-pages" />
+      <ShellOutlet target="admin-settings:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -129,20 +130,55 @@ test("assistant settings-page subcommand uses the target assistant surface and i
     });
 
     assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+    assert.equal(result.summary, 'Generated assistant page "/settings/assistant".');
 
     const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
     assert.match(pageSource, /<AssistantSettingsClientElement target-surface-id="console" \/>/);
 
     const placementSource = await readFile(path.join(appRoot, "src/placement.js"), "utf8");
     assert.match(placementSource, /jskit:assistant\.settings-page\.link:admin:\/settings\/assistant:console/);
-    assert.match(placementSource, /host: "admin-settings"/);
-    assert.match(placementSource, /position: "sub-pages"/);
+    assert.match(placementSource, /target: "admin-settings:sub-pages"/);
     assert.match(placementSource, /componentToken: "local\.main\.ui\.tab-link-item"/);
     assert.match(placementSource, /to: "\.\/assistant"/);
     assert.match(placementSource, /label: "Assistant"/);
   });
 });
 
+test("assistant page subcommand omits the auth guard for a public surface link", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot, {
+      configSource: `export const config = {
+  surfaceAccessPolicies: {
+    public: {}
+  },
+  surfaceDefinitions: {
+    home: {
+      id: "home",
+      pagesRoot: "home",
+      enabled: true,
+      requiresWorkspace: false,
+      accessPolicyId: "public"
+    }
+  },
+  assistantSurfaces: {}
+};
+`
+    });
+
+    const targetFile = "home/assistant/index.vue";
+    await runPageSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /id: "ui-generator\.page\.home\.assistant\.link"/);
+    assert.doesNotMatch(placementSource, /when: \(\{ auth \}\) => Boolean\(auth\?\.authenticated\)/);
+  });
+});
+
 test("assistant page subcommand refuses to overwrite an existing user-owned page", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
@@ -211,7 +247,7 @@ test("assistant settings-page subcommand overwrites an existing page when --forc
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="admin-settings" position="sub-pages" />
+      <ShellOutlet target="admin-settings:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -265,19 +301,20 @@ test("assistant settings-page subcommand requires the target assistant surface o
   });
 });
 
-test("assistant page subcommand rejects target files with a src/pages prefix", async () => {
+test("assistant page subcommand accepts target files with a src/pages prefix", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
 
-    await assert.rejects(
-      () =>
-        runPageSubcommand({
-          appRoot,
-          subcommand: "page",
-          args: ["src/pages/w/[workspaceSlug]/admin/assistant/index.vue"],
-          options: {}
-        }),
-      /must be relative to src\/pages\/, without the src\/pages\/ prefix/
-    );
+    const targetFile = "src/pages/w/[workspaceSlug]/admin/assistant/index.vue";
+    const result = await runPageSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    assert.deepEqual(result.touchedFiles, [targetFile, "src/placement.js"]);
+    const pageSource = await readFile(path.join(appRoot, targetFile), "utf8");
+    assert.match(pageSource, /<AssistantSurfaceClientElement surface-id="admin" \/>/);
   });
 });

package/README.md

@@ -1,91 +0,0 @@
-# @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`