@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/plugins/__tests__/plugin-creation-display-name.test.ts

@@ -0,0 +1,241 @@
+import type { Server as HttpServer } from 'node:http';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { pluginDisplayNameOf, pluginIdentityOf, type AuthUser } from '@bevel-software/platform-shared';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
+import { PluginProvisionService } from '../plugin-provision.service.js';
+import { createPluginCreationRoutes } from '../plugins.routes.js';
+import { CREATE_PLUGIN } from '../plugins.tools.js';
+
+/**
+ * Both doors into plugin creation, through the code each one really runs.
+ *
+ * The dialog POSTs `/api/plugins`; the `create_plugin` tool is a UTCP
+ * DESCRIPTION of that same endpoint — its call template names the URL and
+ * carries the agent's arguments in the request body. So "the two paths" is
+ * one endpoint reached two ways, and what this file holds is that neither
+ * way can quietly derive a different name: the manifest each writes, and the
+ * answer each gives back, are the same for the same typed name.
+ *
+ * Each door gets its own knowledge base, because the point is that ONE name
+ * typed into either produces one file — which two doors into a single tree
+ * could never be asked, the second being refused as a duplicate.
+ */
+
+const KB = 'knowledge-base';
+const ALICE: AuthUser = { id: 'u-alice', email: 'alice@x.io', name: 'Alice' } as AuthUser;
+
+/** The URL the tool definition points a caller at, with the placeholder resolved. */
+function toolUrl(base: string): string {
+  return (CREATE_PLUGIN.tool_call_template as { url: string }).url.replace('${API_URL}', base);
+}
+
+interface Harness {
+  dir: string;
+  svc: PluginProvisionService;
+  baseUrl: string;
+  manifestOf(folder: string): Promise<Record<string, unknown>>;
+  /** The dialog's door: a POST of the body its form builds. */
+  byDialog(name: string, parent?: string): Promise<{ status: number; body: Record<string, unknown> }>;
+  /** The agent's door: the tool's OWN call template — its URL, its body field. */
+  byTool(name: string, parent?: string): Promise<{ status: number; body: Record<string, unknown> }>;
+}
+
+const open: (() => Promise<void>)[] = [];
+
+/** The real provisioning service over a real temp tree, behind the real route. */
+async function makeHarness(): Promise<Harness> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-create-names-'));
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: 'ws-main' }),
+    getWorkspacePath: async () => dir,
+    writeFile: async (_id: string, rel: string, content: string, opts?: { failIfExists?: boolean }) => {
+      const abs = path.join(dir, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      try {
+        await fs.writeFile(abs, content, { encoding: 'utf-8', flag: opts?.failIfExists ? 'wx' : 'w' });
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+          throw Object.assign(new Error(`"${rel}" already exists.`), { status: 409 });
+        }
+        throw err;
+      }
+    },
+  } as unknown as WorkspaceService;
+  const svc = new PluginProvisionService(
+    workspaceService,
+    { runPendingCommit: vi.fn(async () => undefined) },
+    { invalidate: vi.fn() } as unknown as IAccessControl,
+    KB,
+    undefined,
+    new KbPluginSource(new NodeFs()),
+    new NodeFs(),
+  );
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createPluginCreationRoutes(svc, async () => ALICE));
+  const httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  const baseUrl = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+
+  open.push(async () => {
+    await new Promise<void>((r) => httpServer.close(() => r()));
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  const post = async (url: string, name: string, parent?: string) => {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name, parent }),
+    });
+    return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+  };
+
+  return {
+    dir,
+    svc,
+    baseUrl,
+    manifestOf: async (folder) =>
+      JSON.parse(await fs.readFile(path.join(dir, KB, 'Plugins', folder, 'plugin.json'), 'utf-8')),
+    byDialog: (name, parent) => post(`${baseUrl}/api/plugins`, name, parent),
+    // `body_field: 'body'` — the agent calls `create_plugin({ body: {...} })`
+    // and the transport posts that object as the request body.
+    byTool: (name, parent) => post(toolUrl(baseUrl), name, parent),
+  };
+}
+
+afterEach(async () => {
+  for (const close of open.splice(0)) await close();
+});
+
+describe('creation derives and stores the display name the same way through every door', () => {
+  it('stores the name the creator typed, whichever door they came through', async () => {
+    const dialog = await makeHarness();
+    const tool = await makeHarness();
+    const fromDialog = await dialog.byDialog('Sales Team');
+    const fromTool = await tool.byTool('Sales Team');
+    expect([fromDialog.status, fromTool.status]).toEqual([201, 201]);
+
+    const dialogManifest = await dialog.manifestOf('Sales Team');
+    const toolManifest = await tool.manifestOf('Sales Team');
+    // The same file: one renderer, one rule, whatever reached it.
+    expect(dialogManifest).toEqual(toolManifest);
+    expect(dialogManifest).toMatchObject({ name: 'sales-team', displayName: 'Sales Team' });
+    // And the same answer, folder path aside.
+    expect(fromDialog.body).toEqual(fromTool.body);
+
+    // Each answer agrees with the file it wrote, field for field.
+    for (const [answer, manifest] of [
+      [fromDialog.body, dialogManifest],
+      [fromTool.body, toolManifest],
+    ] as const) {
+      expect(answer.name).toBe(manifest.name);
+      expect(answer.displayName).toBe(manifest.displayName);
+      expect(answer.displayName).toBe('Sales Team');
+    }
+  });
+
+  it('derives it the same way inside a grouping folder as at the root', async () => {
+    const h = await makeHarness();
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/Teams'), { recursive: true });
+    const nested = await h.byTool('Sales Team', 'Teams');
+    expect(nested.status).toBe(201);
+    expect(nested.body).toMatchObject({
+      folder: 'Teams/Sales Team',
+      name: 'sales-team',
+      displayName: 'Sales Team',
+    });
+    // Where a plugin LIVES is not an input to what it is called: the leaf is.
+    expect(await h.manifestOf('Teams/Sales Team')).toMatchObject({
+      name: 'sales-team',
+      displayName: 'Sales Team',
+    });
+  });
+
+  it('stores it even when the typed name IS the identifier and IS the folder', async () => {
+    // The case the old rule dropped the field for — and then read the folder
+    // back to fill the gap.
+    const h = await makeHarness();
+    const { body } = await h.byDialog('design');
+    const manifest = await h.manifestOf('design');
+    expect(manifest).toMatchObject({ name: 'design', displayName: 'design' });
+    expect(body).toMatchObject({ name: 'design', displayName: 'design' });
+    expect(pluginDisplayNameOf(manifest)).toBe('design');
+  });
+
+  it('trims what was typed, and the folder takes the trimmed spelling too', async () => {
+    const h = await makeHarness();
+    const { body } = await h.byTool('  Growth Lab  ');
+    expect(body).toMatchObject({ folder: 'Growth Lab', name: 'growth-lab', displayName: 'Growth Lab' });
+    expect(await h.manifestOf('Growth Lab')).toMatchObject({ name: 'growth-lab', displayName: 'Growth Lab' });
+  });
+
+  it('agrees with the discovery source and the shared reader about both names', async () => {
+    const h = await makeHarness();
+    await h.byDialog('Sales Team');
+    await h.byTool('design');
+    // `access.md` is what makes a folder exist to discovery; provisioning
+    // wrote it, so the catalog sees both plugins.
+    const { plugins } = await new KbPluginSource(new NodeFs()).discover(path.join(h.dir, KB));
+    // Walk order, which is the folders' — `design` before `Sales Team`.
+    expect(plugins.map((p) => [p.name, p.displayName])).toEqual([
+      ['design', 'design'],
+      ['sales-team', 'Sales Team'],
+    ]);
+    for (const plugin of plugins) {
+      // The shared reader, given only the manifest, says exactly what
+      // discovery reported — the folder is an input to neither.
+      expect(pluginIdentityOf(plugin.manifest, 'a-completely-different-folder')).toBe(plugin.name);
+      expect(pluginDisplayNameOf(plugin.manifest)).toBe(plugin.displayName);
+    }
+  });
+
+  it('the personal folder carries both names too — it publishes a manifest like any plugin', async () => {
+    const h = await makeHarness();
+    const answer = await h.svc.ensurePersonalPlugin(ALICE);
+    expect(answer).toMatchObject({ name: 'personal-u-alice', displayName: 'personal-u-alice' });
+    expect(await h.manifestOf('personal-u-alice')).toMatchObject({
+      name: 'personal-u-alice',
+      displayName: 'personal-u-alice',
+    });
+  });
+
+  it('an ensure that finds the folder answers with the manifest, not the folder spelling', async () => {
+    const h = await makeHarness();
+    await h.svc.ensurePersonalPlugin(ALICE);
+    // Somebody labelled their own space. The folder is keyed to a user id and
+    // never moves, but the manifest is the only thing that says what it is
+    // called — so the ensure has to read it.
+    const manifestPath = path.join(h.dir, KB, 'Plugins/personal-u-alice/plugin.json');
+    await fs.writeFile(
+      manifestPath,
+      JSON.stringify({ name: 'personal-u-alice', displayName: "Alice's space" }, null, 2),
+    );
+
+    const again = await h.svc.ensurePersonalPlugin(ALICE);
+    expect(again).toMatchObject({
+      created: false,
+      name: 'personal-u-alice',
+      displayName: "Alice's space",
+    });
+    // And the ensure wrote nothing: the label is still the one on disk.
+    expect(JSON.parse(await fs.readFile(manifestPath, 'utf-8')).displayName).toBe("Alice's space");
+  });
+
+  it("the tool's declared output promises the display name it now returns", async () => {
+    const h = await makeHarness();
+    const outputs = CREATE_PLUGIN.outputs as { properties: Record<string, unknown> };
+    expect(Object.keys(outputs.properties)).toContain('displayName');
+    const { body } = await h.byTool('Ops Desk');
+    for (const field of Object.keys(outputs.properties)) expect(body).toHaveProperty(field);
+  });
+});

package/src/modules/plugins/__tests__/plugin-index.service.test.ts

@@ -1,8 +1,10 @@
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, HEXIS_EXTENSION_NS, HEXIS_LINKED_SKILLS_KEY } from '@bevel-software/platform-shared';
 import { PluginIndexService } from '../plugins.service.js';
 import type { PluginLinkIndex } from '../plugin-links.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
@@ -47,11 +49,21 @@ describe('PluginIndexService', () => {
   const toolService = (list: ToolManualSummary[] = []): IToolManualService =>
     ({ listAllSummaries: async () => list }) as unknown as IToolManualService;
 
+  /**
+   * A link index that resolves no memberships — enough to put the service in
+   * the mode every real host runs in (counts follow links), without a tree to
+   * discover. Omit it to get the degraded, inline-only host.
+   */
+  const emptyLinks = () =>
+    ({ membership: async () => ({ bySkill: new Map(), byPlugin: new Map() }) }) as unknown as PluginLinkIndex;
+
   const svc = (opts: {
     access?: IAccessControl;
     skills?: SkillSummary[];
     tools?: ToolManualSummary[];
     workspace?: WorkspaceService;
+    /** Absent: the host that composes no link index — inline-only counts. */
+    links?: PluginLinkIndex;
   } = {}) =>
     new PluginIndexService(
       opts.workspace ?? workspaceService,
@@ -59,6 +71,9 @@ describe('PluginIndexService', () => {
       skillService(opts.skills),
       toolService(opts.tools),
       KB_DIR,
+      new KbPluginSource(new NodeFs()),
+      Date.now,
+      opts.links,
     );
 
   const kb = () => join(root, wsId, KB_DIR);
@@ -68,10 +83,27 @@ describe('PluginIndexService', () => {
    * access.md that makes it exist to the index (a legacy folder without a
    * manifest gets one from the boot step before the index ever runs).
    */
-  const pluginDir = async (name: string) => {
-    await mkdir(join(kb(), 'Plugins', name), { recursive: true });
-    await writeFile(join(kb(), 'Plugins', name, 'plugin.json'), `{"name":"${name.toLowerCase()}"}`);
-    await writeFile(join(kb(), 'Plugins', name, 'access.md'), '---\nread:\n  - everyone\n---\n');
+  const pluginDir = async (
+    folder: string,
+    linkedRoots: string[] = [],
+    names?: { name: string; displayName: string },
+  ) => {
+    await mkdir(join(kb(), 'Plugins', folder), { recursive: true });
+    // Both names, as every manifest carries them: the identity the folder
+    // folds to, and the spelling people see. The folder itself is not an
+    // input to either — creation writes both, and the boot backfill gave
+    // them to the manifests written before the field was mandatory. Pass
+    // `names` for a folder spelled like neither, which is what makes a
+    // reader that consulted it fail.
+    const manifest: Record<string, unknown> = names
+      ? { ...names }
+      : { name: folder.toLowerCase(), displayName: folder };
+    // The roots a manifest links, where `linkedSkillRoots` reads them.
+    if (linkedRoots.length > 0) {
+      manifest.extensions = { [HEXIS_EXTENSION_NS]: { [HEXIS_LINKED_SKILLS_KEY]: linkedRoots } };
+    }
+    await writeFile(join(kb(), 'Plugins', folder, 'plugin.json'), JSON.stringify(manifest));
+    await writeFile(join(kb(), 'Plugins', folder, 'access.md'), '---\nread:\n  - everyone\n---\n');
   };
 
   beforeEach(async () => {
@@ -83,11 +115,17 @@ describe('PluginIndexService', () => {
   test('enumerates Plugins/ folders carrying an access.md, sorted by name', async () => {
     await pluginDir('GTM');
     await pluginDir('Engineering');
+    // A folder spelled like NEITHER of its names: both answers can only have
+    // come from the file, so a reader that fell back to the folder would say
+    // 'mktg' here, or call it 'Mktg'.
+    await pluginDir('Mktg', [], { name: 'marketing', displayName: 'Marketing Platform' });
 
     const catalog = await svc().catalog();
-    // The manifest name is the identity; the folder is what people see.
-    expect(catalog.map((g) => g.name)).toEqual(['engineering', 'gtm']);
+    // The manifest's `name` is the identity and its `displayName` what people
+    // see — both read from the file, neither from the folder.
+    expect(catalog.map((g) => g.name)).toEqual(['engineering', 'gtm', 'marketing']);
     expect(catalog[1]).toMatchObject({ displayName: 'GTM', folders: ['Plugins/GTM'] });
+    expect(catalog[2]).toMatchObject({ displayName: 'Marketing Platform', folders: ['Plugins/Mktg'] });
   });
 
   test('a folder without an access.md is not a plugin', async () => {
@@ -145,6 +183,65 @@ describe('PluginIndexService', () => {
     expect(product.toolCount).toBe(0);
   });
 
+  /**
+   * A plugin's manifest points at roots elsewhere, and the catalog has to say
+   * so: the page uses them to tell a card that LIVES in the plugin from one it
+   * only reaches. A skill under such a root carries its own membership record;
+   * a `.tool` manual beside it carries none, so the root is the only witness —
+   * which is why the tools it brings in are counted here too.
+   */
+  test("serves a plugin's linked roots, and counts the tools that reach it through them", async () => {
+    await pluginDir('GTM', ['Skills/Testing', 'Plugins/Shared/observability']);
+    await pluginDir('Product');
+
+    const catalog = await svc({
+      links: emptyLinks(),
+      tools: tools(
+        'Plugins/GTM/heyreach.tool',
+        'Plugins/Shared/observability/grafana.tool',
+        // A sibling folder sharing a prefix is NOT under the root.
+        'Plugins/Shared/observability-archive/old.tool',
+      ),
+    }).catalog();
+
+    const gtm = catalog.find((g) => g.name === 'gtm')!;
+    expect(gtm.linkedRoots).toEqual(['Skills/Testing', 'Plugins/Shared/observability']);
+    // Its own, plus the one under the linked root; never the archive's.
+    expect(gtm.toolCount).toBe(2);
+    // Product links nothing and holds nothing.
+    const product = catalog.find((g) => g.name === 'product')!;
+    expect(product.linkedRoots).toEqual([]);
+    expect(product.toolCount).toBe(0);
+  });
+
+  test('counts a tool ONCE for a plugin whose linked root sits inside its own folder', async () => {
+    await pluginDir('GTM', ['Plugins/GTM/tools']);
+
+    const catalog = await svc({ links: emptyLinks(), tools: tools('Plugins/GTM/tools/grafana.tool') }).catalog();
+    expect(catalog.find((g) => g.name === 'gtm')!.toolCount).toBe(1);
+  });
+
+  /**
+   * A host that composes no link index counts what each plugin's FOLDER holds
+   * — for skills (see `countThroughLinks`) and, for the same reason, for
+   * tools. Counting a plugin's linked tools there while its linked skills went
+   * uncounted would describe a plugin that exists on no screen.
+   */
+  test('counts tools inline-only when the host has no link index', async () => {
+    await pluginDir('GTM', ['Skills/Testing', 'Plugins/Shared/observability']);
+
+    const catalog = await svc({
+      skills: skills('Plugins/GTM/outreach', 'Skills/Testing/test-shared-linking'),
+      tools: tools('Plugins/GTM/heyreach.tool', 'Plugins/Shared/observability/grafana.tool'),
+    }).catalog();
+
+    // The roots are still SERVED — the page needs them to draw the pill; it is
+    // the counting that degrades, and it degrades the same way for both kinds.
+    const gtm = catalog.find((g) => g.name === 'gtm')!;
+    expect(gtm.linkedRoots).toEqual(['Skills/Testing', 'Plugins/Shared/observability']);
+    expect(gtm).toMatchObject({ skillCount: 1, toolCount: 1 });
+  });
+
   test("counts the linked skills a plugin's members cannot read, from the unfiltered link index", async () => {
     await pluginDir('GTM');
     await pluginDir('Product');
@@ -165,6 +262,7 @@ describe('PluginIndexService', () => {
       skillService(skills('Skills/Eng/deploy', 'Skills/Eng/rollback', 'Plugins/Product/roadmap')),
       toolService(),
       KB_DIR,
+      new KbPluginSource(new NodeFs()),
       Date.now,
       links,
     ).catalog();
@@ -178,6 +276,49 @@ describe('PluginIndexService', () => {
     expect((await svc().catalog()).every((g) => g.brokenLinks === 0)).toBe(true);
   });
 
+  test("marks a plugin private when its access.md's own block denies everyone and names only people", async () => {
+    await pluginDir('GTM'); // read: everyone — discoverable, not private
+    await pluginDir('Mine');
+    await writeFile(
+      join(kb(), 'Plugins', 'Mine', 'access.md'),
+      '---\n# the file\nread:\n  - deny everyone\n  - Ali Vega <ali@x.io>\n---\nread:\n  - deny everyone\n  - Ali Vega <ali@x.io>\n',
+    );
+    // A role beside the denial is a roster, not a private list.
+    await pluginDir('Team');
+    await writeFile(
+      join(kb(), 'Plugins', 'Team', 'access.md'),
+      '---\nread:\n  - deny everyone\n  - Sales Team\n---\nread:\n  - Sales Team\n',
+    );
+    // A frontmatter that never mentions everyone makes no statement.
+    await pluginDir('Quiet');
+    await writeFile(join(kb(), 'Plugins', 'Quiet', 'access.md'), '---\nread: []\n---\nread:\n  - Ali Vega <ali@x.io>\n');
+
+    const catalog = await svc().catalog();
+    expect(Object.fromEntries(catalog.map((g) => [g.name, g.isPrivate]))).toEqual({
+      gtm: false,
+      mine: true,
+      team: false,
+      quiet: false,
+    });
+  });
+
+  test("carries what discovery left out of a plugin, in that plugin's entry, without the folder prefix", async () => {
+    await pluginDir('GTM');
+    await mkdir(join(kb(), 'Plugins', 'Ado'), { recursive: true });
+    await writeFile(
+      join(kb(), 'Plugins', 'Ado', 'plugin.bundle.json'),
+      JSON.stringify({ name: 'ado', mcpProfile: 'global', sourceSkillRoots: ['../escape'] }),
+    );
+    const catalog = await svc().catalog();
+    const ado = catalog.find((g) => g.name === 'ado')!;
+    expect(ado.warnings).toEqual([
+      'sourceSkillRoots entry "../escape" is not a folder path — ignored',
+      'mcpProfile "global" named but no registry could be read',
+    ]);
+    // Nothing of that is GTM's.
+    expect(catalog.find((g) => g.name === 'gtm')!.warnings).toEqual([]);
+  });
+
   test('resolves principals on the plugin folder', async () => {
     await pluginDir('GTM');
 

package/src/modules/plugins/__tests__/plugin-links.service.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -80,9 +82,10 @@ describe('PluginLinksService', () => {
     await write('Skills/Eng/deploy/SKILL.md', '---\ndescription: Ship it.\n---\n');
     await write('Skills/Eng/rollback/SKILL.md', '---\ndescription: Undo it.\n---\n');
 
-    access = new AccessControlService(workspaceService, KB_DIR);
-    skills = new SkillService(workspaceService, access, KB_DIR);
-    index = new PluginLinkIndex(workspaceService, skills, access, KB_DIR);
+    const disk = new NodeFs();
+    access = new AccessControlService(workspaceService, KB_DIR, disk);
+    skills = new SkillService(workspaceService, access, KB_DIR, disk);
+    index = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, new KbPluginSource(disk));
     svc = new PluginLinksService(workspaceService, driver, access, skills, index, KB_DIR);
   });
   afterEach(() => fs.rm(root, { recursive: true, force: true }));
@@ -193,21 +196,15 @@ describe('PluginLinksService', () => {
     await expect(svc.link(manager, 'gtm', '../etc')).rejects.toMatchObject({ status: 422, payload: { kind: 'bad-root' } });
   });
 
-  it('refuses a root that holds a retired skill anywhere beneath it — the grant would reach it', async () => {
+  it('links a root whose skills carry any frontmatter — a governance key is no longer a refusal', async () => {
     await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
     await write('Skills/Eng/old-deploy/SKILL.md', '---\ndescription: Gone.\nmetadata:\n  lifecycle: retired\n---\n');
     access.invalidate(wsId);
     skills.invalidate();
 
-    await expect(svc.link(manager, 'gtm', 'Skills/Eng')).rejects.toMatchObject({
-      status: 422,
-      payload: { kind: 'retired-skills', retired: ['Skills/Eng/old-deploy'] },
-    });
-    await expect(svc.link(manager, 'gtm', 'Skills/Eng/old-deploy')).rejects.toMatchObject({ status: 422 });
-    // The active skill on its own is fine.
-    await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
-    expect(await read('Skills/Eng/deploy/access.md')).toContain('plugin/gtm/read');
-    expect(await access.canRead(wsId, member.email, 'Skills/Eng/old-deploy/SKILL.md')).toBe(false);
+    const result = await svc.link(manager, 'gtm', 'Skills/Eng');
+    expect(result.skills.sort()).toEqual(['Skills/Eng/deploy', 'Skills/Eng/old-deploy', 'Skills/Eng/rollback']);
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/old-deploy/SKILL.md')).toBe(true);
   });
 
   it('unlink removes the entry and revokes the tokens when the actor may edit the skill', async () => {

package/src/modules/plugins/__tests__/plugin-names.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import {
+  pluginDisplayNameOf,
+  pluginIdentityOf,
+  renderPluginManifest,
+} from '@bevel-software/platform-shared';
+
+/**
+ * THE rule, in one place: the identifier is the manifest's `name`; the
+ * display name is the manifest's `displayName`, else that same `name`. The
+ * folder a plugin happens to live in is not an input to either — it used to
+ * be, which made moving or re-casing a folder a silent rename.
+ */
+describe('the one display-name rule', () => {
+  it('reads the display name from the manifest and nothing else', () => {
+    expect(pluginDisplayNameOf({ name: 'sales-team', displayName: 'Sales Team' })).toBe('Sales Team');
+    // No `displayName`: the identifier is what it is called. There is nowhere
+    // else to look — the function is not given a folder to fall back to.
+    expect(pluginDisplayNameOf({ name: 'design' })).toBe('design');
+    // Whitespace is never what someone typed.
+    expect(pluginDisplayNameOf({ name: 'gtm', displayName: '  Go To Market  ' })).toBe('Go To Market');
+    // A blank field is no answer; the name stands.
+    expect(pluginDisplayNameOf({ name: 'gtm', displayName: '   ' })).toBe('gtm');
+    expect(pluginDisplayNameOf({ name: 'gtm', displayName: 42 })).toBe('gtm');
+    // A manifest naming something no identifier still SAYS what it is called.
+    expect(pluginDisplayNameOf({ name: 'Not An Identifier' })).toBe('Not An Identifier');
+    // Nothing to read: empty, for the caller that resolved an identity to use.
+    expect(pluginDisplayNameOf({})).toBe('');
+    expect(pluginDisplayNameOf(null)).toBe('');
+    expect(pluginDisplayNameOf({ name: 42 })).toBe('');
+  });
+
+  it('never lets the display name reach back into the identifier', () => {
+    const manifest = { name: 'sales-team', displayName: 'Something Else Entirely' };
+    expect(pluginIdentityOf(manifest, 'Sales Team')).toBe('sales-team');
+    expect(pluginIdentityOf(manifest, 'anything-at-all')).toBe('sales-team');
+  });
+
+  describe('renderPluginManifest', () => {
+    it('always writes displayName — the spelling it is given, which creation takes from its creator', () => {
+      expect(JSON.parse(renderPluginManifest('Sales Team'))).toMatchObject({
+        name: 'sales-team',
+        displayName: 'Sales Team',
+      });
+    });
+
+    it('writes it even when it equals the identifier, so no reader needs a second rule', () => {
+      const manifest = JSON.parse(renderPluginManifest('design'));
+      expect(manifest).toMatchObject({ name: 'design', displayName: 'design' });
+      expect(pluginDisplayNameOf(manifest)).toBe('design');
+    });
+
+    it('trims the spelling it is given, and falls back to the identifier when it says nothing', () => {
+      // Creation hands over the name its creator typed — the folder's leaf and
+      // the display name are the one string, so the two can never disagree.
+      expect(JSON.parse(renderPluginManifest('  Sales Team  '))).toMatchObject({
+        name: 'sales-team',
+        displayName: 'Sales Team',
+      });
+      // A blank one is not a name; the identifier stands rather than a field
+      // that is present and says nothing.
+      expect(JSON.parse(renderPluginManifest('   ')).displayName).toBe('plugin');
+    });
+
+    it('round-trips: what the renderer writes is what the reader says', () => {
+      for (const folder of ['Sales Team', 'design', 'GTM', 'ÜbÜr Tëam']) {
+        const manifest = JSON.parse(renderPluginManifest(folder));
+        expect(pluginDisplayNameOf(manifest)).toBe(folder);
+        expect(pluginIdentityOf(manifest, 'some-other-folder')).toBe(manifest.name);
+      }
+    });
+
+    it('invents nothing else', () => {
+      expect(Object.keys(JSON.parse(renderPluginManifest('GTM')))).toEqual(['$schema', 'name', 'displayName']);
+    });
+  });
+});