@jskit-ai/assistant 0.1.74 → 0.1.76

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/assistant",
-  version: "0.1.74",
+  version: "0.1.76",
   kind: "generator",
   description: "Install assistant runtime/config for one surface and scaffold assistant pages at explicit target files.",
   options: {
@@ -49,14 +49,7 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Link placement",
-      promptHint: "Optional target for the generated page link placement (format: host:position)."
-    },
-    "link-component-token": {
-      required: false,
-      inputType: "text",
-      defaultValue: "",
-      promptLabel: "Link component token",
-      promptHint: "Optional component token override for the generated page link placement."
+      promptHint: "Optional semantic target for the generated page link placement (format: area.slot)."
     },
     "link-to": {
       required: false,
@@ -169,7 +162,7 @@ export default Object.freeze({
             descriptionKey: "page-target-file"
           }
         ],
-        optionNames: ["name", "link-placement", "link-component-token", "link-to", "force"],
+        optionNames: ["name", "link-placement", "link-to", "force"],
         notes: [
           "The target file decides where the page lives.",
           "Page-link placement follows the same inference rules as ui-generator page.",
@@ -189,7 +182,7 @@ export default Object.freeze({
               "npx jskit generate assistant page \\",
               "  admin/ops/copilot/index.vue \\",
               "  --name \"Copilot\" \\",
-              "  --link-placement shell-layout:top-right"
+              "  --link-placement shell.status"
             ]
           }
         ]
@@ -206,7 +199,7 @@ export default Object.freeze({
             descriptionKey: "page-target-file"
           }
         ],
-        optionNames: ["surface", "name", "link-placement", "link-component-token", "link-to", "force"],
+        optionNames: ["surface", "name", "link-placement", "link-to", "force"],
         requiredOptionNames: ["surface"],
         notes: [
           "The target file decides where the settings page lives.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant",
-  "version": "0.1.74",
+  "version": "0.1.76",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -9,6 +9,6 @@
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.65"
+    "@jskit-ai/kernel": "0.1.67"
   }
 }

package/src/server/buildTemplateContext.js

@@ -12,7 +12,10 @@ async function buildTemplateContext({ appRoot, options } = {}) {
   const settingsSurface = resolveSurfaceDefinition(appConfig, options?.["settings-surface"], "settings-surface");
   const configScope = normalizeConfigScope(options?.["config-scope"]);
 
-  assertAssistantSurfaceIsAvailable(appConfig, runtimeSurface.id);
+  assertAssistantSurfaceIsAvailable(appConfig, runtimeSurface.id, {
+    settingsSurfaceId: settingsSurface.id,
+    configScope
+  });
 
   if (configScope === "workspace" && runtimeSurface.requiresWorkspace !== true) {
     throw new Error(

package/src/server/pageSupport.js

@@ -16,6 +16,14 @@ function resolveLinkToPropLine(linkTo = "") {
   return `      to: ${JSON.stringify(linkTo)},\n`;
 }
 
+function resolveOwnerLine(owner = "") {
+  const normalizedOwner = normalizeText(owner);
+  if (!normalizedOwner) {
+    return "";
+  }
+  return `    owner: ${JSON.stringify(normalizedOwner)},\n`;
+}
+
 function resolveTemplateFilePath(relativePath = "") {
   return fileURLToPath(new URL(relativePath, import.meta.url));
 }
@@ -49,7 +57,6 @@ async function resolveAssistantPageGenerationContext({
     targetFile,
     context,
     placement: options?.["link-placement"],
-    componentToken: options?.["link-component-token"],
     linkTo: options?.["link-to"]
   });
 
@@ -57,7 +64,7 @@ async function resolveAssistantPageGenerationContext({
     pageTarget,
     pageLabel: normalizeText(options?.name) || pageTarget.defaultName,
     linkPlacementTarget: String(linkTarget.placementTarget?.id || ""),
-    linkComponentToken: String(linkTarget.componentToken || ""),
+    linkOwnerLine: resolveOwnerLine(linkTarget.placementTarget?.owner || ""),
     linkWorkspaceSuffix: pageTarget.routeUrlSuffix,
     linkNonWorkspaceSuffix: pageTarget.routeUrlSuffix,
     linkWhenLine: String(linkTarget.whenLine || ""),
@@ -76,9 +83,10 @@ function renderAssistantPageLinkPlacementBlock({
     "  addPlacement({\n" +
     `    id: "${String(pageTarget?.placementId || "")}",\n` +
     `    target: "${String(generationContext?.linkPlacementTarget || "")}",\n` +
+    `${String(generationContext?.linkOwnerLine || "")}` +
+    "    kind: \"link\",\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` +

package/src/server/subcommands/page.js

@@ -30,7 +30,7 @@ async function runGeneratorSubcommand({
   }
 
   const targetFile = requireSinglePositionalTargetFile(args, { context: "assistant page" });
-  rejectUnexpectedOptions(options, ["name", "link-placement", "link-component-token", "link-to", "force"], {
+  rejectUnexpectedOptions(options, ["name", "link-placement", "link-to", "force"], {
     context: "assistant page"
   });
   const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")

package/src/server/subcommands/settingsPage.js

@@ -31,7 +31,7 @@ async function runGeneratorSubcommand({
   }
 
   const targetFile = requireSinglePositionalTargetFile(args, { context: "assistant settings-page" });
-  rejectUnexpectedOptions(options, ["surface", "name", "link-placement", "link-component-token", "link-to", "force"], {
+  rejectUnexpectedOptions(options, ["surface", "name", "link-placement", "link-to", "force"], {
     context: "assistant settings-page"
   });
   const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")

package/src/server/support.js

@@ -49,11 +49,25 @@ function resolveSurfaceDefinition(appConfig = {}, surfaceId = "", optionName = "
   });
 }
 
-function assertAssistantSurfaceIsAvailable(appConfig = {}, surfaceId = "") {
+function assertAssistantSurfaceIsAvailable(appConfig = {}, surfaceId = "", expected = {}) {
   const assistantSurfaces =
     appConfig && typeof appConfig.assistantSurfaces === "object" && !Array.isArray(appConfig.assistantSurfaces)
       ? appConfig.assistantSurfaces
       : {};
+  const existingSurface = assistantSurfaces[surfaceId];
+  if (!existingSurface) {
+    return;
+  }
+
+  const expectedSettingsSurfaceId = normalizeSurfaceId(expected?.settingsSurfaceId);
+  const expectedConfigScope = normalizeConfigScope(expected?.configScope);
+  const existingSettingsSurfaceId = normalizeSurfaceId(existingSurface?.settingsSurfaceId);
+  const existingConfigScope = normalizeConfigScope(existingSurface?.configScope);
+
+  if (existingSettingsSurfaceId === expectedSettingsSurfaceId && existingConfigScope === expectedConfigScope) {
+    return;
+  }
+
   if (assistantSurfaces[surfaceId]) {
     throw new Error(`assistant generator surface "${surfaceId}" already has an assistant configured in config/public.js.`);
   }

package/test/buildTemplateContext.test.js

@@ -84,7 +84,7 @@ test("buildTemplateContext rejects workspace config scope for a non-workspace as
   });
 });
 
-test("buildTemplateContext rejects duplicate assistant surfaces already configured in public config", async () => {
+test("buildTemplateContext accepts an already-configured matching assistant surface", async () => {
   await withTempApp(async (appRoot) => {
     await writeFile(
       path.join(appRoot, "config", "public.js"),
@@ -104,13 +104,48 @@ test("buildTemplateContext rejects duplicate assistant surfaces already configur
       "utf8"
     );
 
+    const context = await buildTemplateContext({
+      appRoot,
+      options: {
+        surface: "app",
+        "settings-surface": "console",
+        "config-scope": "global"
+      }
+    });
+
+    assert.equal(context.__ASSISTANT_SETTINGS_SURFACE_ID__, "console");
+    assert.equal(context.__ASSISTANT_CONFIG_SCOPE__, "global");
+  });
+});
+
+test("buildTemplateContext rejects conflicting assistant surfaces already configured in public config", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFile(
+      path.join(appRoot, "config", "public.js"),
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", enabled: true, requiresWorkspace: false, accessPolicyId: "authenticated" },
+    admin: { id: "admin", enabled: true, requiresWorkspace: true, accessPolicyId: "workspace_member" },
+    console: { id: "console", enabled: true, requiresWorkspace: false, accessPolicyId: "console_owner" }
+  },
+  assistantSurfaces: {
+    app: {
+      settingsSurfaceId: "console",
+      configScope: "global"
+    }
+  }
+};
+`,
+      "utf8"
+    );
+
     await assert.rejects(
       () =>
         buildTemplateContext({
           appRoot,
           options: {
             surface: "app",
-            "settings-surface": "console",
+            "settings-surface": "admin",
             "config-scope": "global"
           }
         }),

package/test/subcommands.test.js

@@ -25,6 +25,61 @@ function toPagePath(targetFile = "") {
   return path.join("src/pages", targetFile);
 }
 
+function renderTopologyVariant(outlet, { linkRenderer = "" } = {}) {
+  const rendererLines = linkRenderer
+    ? `,
+      renderers: {
+        link: "${linkRenderer}"
+      }`
+    : "";
+  return `{
+      outlet: "${outlet}"${rendererLines}
+    }`;
+}
+
+function renderTopologyEntry({
+  id = "",
+  owner = "",
+  surfaces = ["*"],
+  defaultPlacement = false,
+  outlet = "",
+  linkRenderer = ""
+} = {}) {
+  const ownerLine = owner ? `    owner: "${owner}",\n` : "";
+  const defaultLine = defaultPlacement ? "    default: true,\n" : "";
+  return `  {
+    id: "${id}",
+${ownerLine}    surfaces: ${JSON.stringify(surfaces)},
+${defaultLine}    variants: {
+      compact: ${renderTopologyVariant(outlet, { linkRenderer })},
+      medium: ${renderTopologyVariant(outlet, { linkRenderer })},
+      expanded: ${renderTopologyVariant(outlet, { linkRenderer })}
+    }
+  }`;
+}
+
+async function writePlacementTopology(appRoot, entries = []) {
+  const defaultEntries = [
+    renderTopologyEntry({
+      id: "shell.primary-nav",
+      surfaces: ["*"],
+      defaultPlacement: true,
+      outlet: "shell-layout:primary-menu",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    })
+  ];
+  await writeFileInApp(
+    appRoot,
+    "src/placementTopology.js",
+    `export default {
+  placements: [
+${[...defaultEntries, ...entries].join(",\n")}
+  ]
+};
+`
+  );
+}
+
 async function writeAppFixture(appRoot, { configSource = "" } = {}) {
   await writeFileInApp(
     appRoot,
@@ -73,6 +128,7 @@ export default function getPlacements() {
 }
 `
   );
+  await writePlacementTopology(appRoot);
 }
 
 test("assistant page subcommand creates a runtime page at an explicit target file", async () => {
@@ -96,7 +152,9 @@ 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, /target: "shell-layout:primary-menu"/);
+    assert.match(placementSource, /target: "shell\.primary-nav"/);
+    assert.match(placementSource, /kind: "link"/);
+    assert.doesNotMatch(placementSource, /componentToken:/);
     assert.match(placementSource, /label: "Copilot"/);
     assert.match(placementSource, /scopedSuffix: "\/ops\/copilot"/);
   });
@@ -105,6 +163,15 @@ test("assistant page subcommand creates a runtime page at an explicit target fil
 test("assistant settings-page subcommand uses the target assistant surface and infers parent subpage placement", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "admin-settings",
+        surfaces: ["admin"],
+        outlet: "admin-settings:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/w/[workspaceSlug]/admin/settings/index.vue",
@@ -137,8 +204,9 @@ test("assistant settings-page subcommand uses the target assistant surface and i
 
     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, /target: "admin-settings:sub-pages"/);
-    assert.match(placementSource, /componentToken: "local\.main\.ui\.surface-aware-menu-link-item"/);
+    assert.match(placementSource, /target: "page\.section-nav"/);
+    assert.match(placementSource, /owner: "admin-settings"/);
+    assert.doesNotMatch(placementSource, /componentToken: "local\.main\.ui\.surface-aware-menu-link-item"/);
     assert.match(placementSource, /to: "\.\/assistant"/);
     assert.match(placementSource, /label: "Assistant"/);
   });
@@ -241,6 +309,15 @@ test("assistant page subcommand overwrites an existing page when --force is pass
 test("assistant settings-page subcommand overwrites an existing page when --force is passed", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "admin-settings",
+        surfaces: ["admin"],
+        outlet: "admin-settings:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/w/[workspaceSlug]/admin/settings/index.vue",