@jskit-ai/assistant 0.1.40 → 0.1.41

package/test/packageDescriptor.test.js

@@ -2,51 +2,47 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import descriptor from "../package.descriptor.mjs";
 
-function findFileMutation(id) {
-  const mutations = Array.isArray(descriptor?.mutations?.files) ? descriptor.mutations.files : [];
-  return mutations.find((entry) => String(entry?.id || "") === id) || null;
-}
-
 function findTextMutation(id) {
   const mutations = Array.isArray(descriptor?.mutations?.text) ? descriptor.mutations.text : [];
   return mutations.find((entry) => String(entry?.id || "") === id) || null;
 }
 
-test("assistant descriptor exposes per-surface generation options and depends on assistant-runtime", () => {
+test("assistant descriptor exposes setup as the primary command and still depends on assistant-runtime", () => {
   assert.equal(descriptor.kind, "generator");
+  assert.equal(descriptor.metadata?.generatorPrimarySubcommand, "setup");
   assert.equal(descriptor.options?.surface?.required, true);
+  assert.equal(descriptor.options?.surface?.validationType, "enabled-surface-id");
   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"]?.required, false);
+  assert.equal(descriptor.options?.name?.required, false);
+  assert.equal(descriptor.options?.["link-placement"]?.required, false);
   assert.deepEqual(descriptor.dependsOn, ["@jskit-ai/assistant-runtime"]);
 });
 
-test("assistant descriptor generates only assistant runtime/settings pages and no local runtime package", () => {
-  const runtimePage = findFileMutation("assistant-page-runtime");
-  const settingsPageStandard = findFileMutation("assistant-page-settings-standard");
-  const settingsPageAdmin = findFileMutation("assistant-page-settings-admin");
+test("assistant descriptor defines explicit page subcommands and setup-only mutations", () => {
+  const subcommands = descriptor.metadata?.generatorSubcommands || {};
   const fileMutations = Array.isArray(descriptor?.mutations?.files) ? descriptor.mutations.files : [];
 
-  assert.equal(runtimePage?.toSurface, "${option:surface|lower}");
-  assert.equal(runtimePage?.toSurfacePath, "assistant/index.vue");
-  assert.equal(settingsPageStandard?.toSurfacePath, "settings/${option:settings-route-path|path}/index.vue");
-  assert.equal(settingsPageAdmin?.toSurfacePath, "workspace/settings/${option:settings-route-path|path}/index.vue");
-  assert.equal(fileMutations.length, 3);
+  assert.equal(subcommands.setup?.description?.length > 0, true);
+  assert.equal(subcommands.page?.entrypoint, "src/server/subcommands/page.js");
+  assert.equal(subcommands["settings-page"]?.entrypoint, "src/server/subcommands/settingsPage.js");
+  assert.equal(subcommands.page?.positionalArgs?.[0]?.name, "target-file");
+  assert.equal(subcommands["settings-page"]?.requiredOptionNames?.[0], "surface");
+  assert.equal(subcommands.page?.optionNames?.includes("force"), true);
+  assert.equal(subcommands["settings-page"]?.optionNames?.includes("force"), true);
+  assert.equal(fileMutations.length, 0);
 });
 
-test("assistant descriptor appends menu placement, settings menu placement, and per-surface config entries", () => {
-  const menuPlacement = findTextMutation("assistant-placement-menu");
-  const settingsPlacement = findTextMutation("assistant-settings-menu-placement");
+test("assistant descriptor appends only setup config and env entries", () => {
   const publicConfig = findTextMutation("assistant-public-surface-config");
   const serverConfig = findTextMutation("assistant-server-surface-config");
   const envBlock = findTextMutation("assistant-ai-prefixed-env");
+  const textMutations = Array.isArray(descriptor?.mutations?.text) ? descriptor.mutations.text : [];
 
-  assert.match(String(menuPlacement?.value || ""), /assistant\.generated\.menu:\$\{option:surface\|lower\}/);
-  assert.match(String(menuPlacement?.value || ""), /surfaces: \["\$\{option:surface\|lower\}"\]/);
-  assert.match(String(settingsPlacement?.value || ""), /assistant\.generated\.settings\.menu:\$\{option:surface\|lower\}/);
-  assert.match(String(settingsPlacement?.value || ""), /host: "__ASSISTANT_SETTINGS_HOST__"/);
-  assert.match(String(settingsPlacement?.value || ""), /position: "primary-menu"/);
+  assert.equal(textMutations.length, 3);
   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\}/);

package/test/subcommands.test.js

@@ -0,0 +1,283 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { runGeneratorSubcommand as runPageSubcommand } from "../src/server/subcommands/page.js";
+import { runGeneratorSubcommand as runSettingsPageSubcommand } from "../src/server/subcommands/settingsPage.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "assistant-subcommands-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeFileInApp(appRoot, relativePath, source) {
+  const absoluteFile = path.join(appRoot, relativePath);
+  await mkdir(path.dirname(absoluteFile), { recursive: true });
+  await writeFile(absoluteFile, source, "utf8");
+}
+
+function toPagePath(targetFile = "") {
+  return path.join("src/pages", targetFile);
+}
+
+async function writeAppFixture(appRoot) {
+  await writeFileInApp(
+    appRoot,
+    "config/public.js",
+    `export const config = {
+  surfaceDefinitions: {
+    admin: {
+      id: "admin",
+      pagesRoot: "w/[workspaceSlug]/admin",
+      enabled: true,
+      requiresWorkspace: true,
+      accessPolicyId: "workspace_member"
+    },
+    console: {
+      id: "console",
+      pagesRoot: "console",
+      enabled: true,
+      requiresWorkspace: false,
+      accessPolicyId: "console_owner"
+    }
+  },
+  assistantSurfaces: {}
+};
+`
+  );
+  await writeFileInApp(
+    appRoot,
+    "src/components/ShellLayout.vue",
+    `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet host="shell-layout" position="top-right" />
+  </div>
+</template>
+`
+  );
+  await writeFileInApp(
+    appRoot,
+    "src/placement.js",
+    `function addPlacement() {}
+
+export { addPlacement };
+export default function getPlacements() {
+  return [];
+}
+`
+  );
+}
+
+test("assistant page subcommand creates a runtime page at an explicit target file", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/ops/copilot/index.vue";
+    const result = await runPageSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {}
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /<AssistantSurfaceClientElement surface-id="admin" \/>/);
+
+    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, /label: "Copilot"/);
+    assert.match(placementSource, /workspaceSuffix: "\/ops\/copilot"/);
+  });
+});
+
+test("assistant settings-page subcommand uses the target assistant surface and infers parent subpage placement", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/w/[workspaceSlug]/admin/settings/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="admin-settings" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const targetFile = "w/[workspaceSlug]/admin/settings/index/assistant/index.vue";
+    const result = await runSettingsPageSubcommand({
+      appRoot,
+      subcommand: "settings-page",
+      args: [targetFile],
+      options: {
+        surface: "console"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+
+    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, /componentToken: "local\.main\.ui\.tab-link-item"/);
+    assert.match(placementSource, /to: "\.\/assistant"/);
+    assert.match(placementSource, /label: "Assistant"/);
+  });
+});
+
+test("assistant page subcommand refuses to overwrite an existing user-owned page", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/assistant/index.vue";
+    await writeFileInApp(
+      appRoot,
+      toPagePath(targetFile),
+      `<template>
+  <div>custom page</div>
+</template>
+`
+    );
+
+    await assert.rejects(
+      () =>
+        runPageSubcommand({
+          appRoot,
+          subcommand: "page",
+          args: [targetFile],
+          options: {}
+        }),
+      /will not overwrite existing page/
+    );
+  });
+});
+
+test("assistant page subcommand overwrites an existing page when --force is passed", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/assistant/index.vue";
+    await writeFileInApp(
+      appRoot,
+      toPagePath(targetFile),
+      `<template>
+  <div>custom assistant page</div>
+</template>
+`
+    );
+
+    const result = await runPageSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        force: "true"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+    assert.equal(result.summary, 'Regenerated assistant page "/assistant".');
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /<AssistantSurfaceClientElement surface-id="admin" \/>/);
+    assert.doesNotMatch(pageSource, /custom assistant page/);
+  });
+});
+
+test("assistant settings-page subcommand overwrites an existing page when --force is passed", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/w/[workspaceSlug]/admin/settings/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="admin-settings" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const targetFile = "w/[workspaceSlug]/admin/settings/index/assistant/index.vue";
+    await writeFileInApp(
+      appRoot,
+      toPagePath(targetFile),
+      `<template>
+  <div>custom settings page</div>
+</template>
+`
+    );
+
+    const result = await runSettingsPageSubcommand({
+      appRoot,
+      subcommand: "settings-page",
+      args: [targetFile],
+      options: {
+        surface: "console",
+        force: "true"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+    assert.equal(result.summary, 'Regenerated assistant page "/settings/assistant".');
+
+    const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
+    assert.match(pageSource, /<AssistantSettingsClientElement target-surface-id="console" \/>/);
+    assert.doesNotMatch(pageSource, /custom settings page/);
+  });
+});
+
+test("assistant settings-page subcommand requires the target assistant surface option", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await assert.rejects(
+      () =>
+        runSettingsPageSubcommand({
+          appRoot,
+          subcommand: "settings-page",
+          args: ["w/[workspaceSlug]/admin/settings/assistant/index.vue"],
+          options: {}
+        }),
+      /assistant generator requires --surface/
+    );
+  });
+});
+
+test("assistant page subcommand rejects 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/
+    );
+  });
+});