@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/modules/tool-manuals/__tests__/mcp-json-discovery.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { descriptorsFromMcpJson } from '../mcp-json-discovery.js';
+
+afterEach(() => vi.restoreAllMocks());
+
+const MANIFEST = JSON.stringify({
+  name: 'gtm',
+  extensions: {
+    'software.bevel.hexis': {
+      mcpServers: {
+        vendor: {
+          headers: { Authorization: 'Bearer ${VENDOR_KEY}' },
+          variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+          description: 'Vendor API',
+        },
+        localbox: { local: true },
+      },
+    },
+  },
+});
+
+describe('descriptorsFromMcpJson', () => {
+  it('synthesizes descriptors keyed by server name, path at mcp.json', () => {
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({ mcpServers: { notion: { type: 'streamable-http', url: 'https://mcp.notion.com/mcp' } } }),
+      null,
+    );
+    expect(out).toEqual([
+      {
+        slug: 'notion',
+        name: 'notion',
+        path: 'Plugins/GTM/mcp.json',
+        type: 'mcp',
+        url: 'https://mcp.notion.com/mcp',
+      },
+    ]);
+  });
+
+  it('merges extension auth over mcp.json literals and carries variables + description', () => {
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({
+        mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp', headers: { 'X-V': '2' } } },
+      }),
+      MANIFEST,
+    );
+    expect(out[0]).toMatchObject({
+      headers: { 'X-V': '2', Authorization: 'Bearer ${VENDOR_KEY}' },
+      variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+      description: 'Vendor API',
+    });
+  });
+
+  it('marks extension-flagged servers and every stdio server local-only', () => {
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({
+        mcpServers: {
+          localbox: { type: 'streamable-http', url: 'http://localhost:9000/mcp' },
+          indexer: { type: 'stdio', command: 'npx', args: ['-y', 'indexer'] },
+        },
+      }),
+      MANIFEST,
+    );
+    expect(out.find((d) => d.name === 'localbox')?.remote).toBe(false);
+    const stdio = out.find((d) => d.name === 'indexer');
+    expect(stdio?.remote).toBe(false);
+    expect(stdio?.stdio).toEqual({ command: 'npx', args: ['-y', 'indexer'], env: undefined, cwd: undefined });
+  });
+
+  it('skips a malformed entry without losing its siblings', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({
+        mcpServers: {
+          'Bad Name!': { type: 'streamable-http', url: 'https://x.example' },
+          nourl: { type: 'streamable-http' },
+          odd: { type: 'carrier-pigeon' },
+          ok: { type: 'streamable-http', url: 'https://ok.example/mcp' },
+        },
+      }),
+      null,
+    );
+    expect(out.map((d) => d.name)).toEqual(['ok']);
+  });
+
+  it('ignores malformed extension headers instead of spreading them into keys', () => {
+    // A string spread into the merge would scatter its indices ('0', '1', …)
+    // into header names; a malformed extension must cost its own data only.
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({
+        mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp', headers: { 'X-V': '2' } } },
+      }),
+      JSON.stringify({
+        name: 'gtm',
+        extensions: { 'software.bevel.hexis': { mcpServers: { vendor: { headers: 'Bearer oops' } } } },
+      }),
+    );
+    expect(out).toHaveLength(1);
+    expect(out[0].headers).toEqual({ 'X-V': '2' });
+  });
+
+  it('skips a server whose variables declaration is malformed, keeping siblings', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // A dropped declaration would silently re-scope a credential (undeclared
+    // defaults to the shared admin row), so a bad entry takes the SERVER
+    // offline — never just the entry, and never its siblings.
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({
+        mcpServers: {
+          vendor: { type: 'streamable-http', url: 'https://v.example/mcp' },
+          ok: { type: 'streamable-http', url: 'https://ok.example/mcp' },
+        },
+      }),
+      JSON.stringify({
+        name: 'gtm',
+        extensions: {
+          'software.bevel.hexis': {
+            mcpServers: { vendor: { variables: [{ name: 'bad name!', scope: 'user' }] } },
+          },
+        },
+      }),
+    );
+    expect(out.map((d) => d.name)).toEqual(['ok']);
+  });
+
+  it('applies the .tool declaration rules: no reserved names, no duplicates, gated OAuth URLs, string authParams', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const declare = (variables: unknown) =>
+      descriptorsFromMcpJson(
+        'GTM',
+        JSON.stringify({ mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),
+        JSON.stringify({
+          name: 'gtm',
+          extensions: { 'software.bevel.hexis': { mcpServers: { vendor: { variables } } } },
+        }),
+      ).map((d) => d.name);
+    // A re-declared platform-seeded name would shadow the seeding; a
+    // duplicate makes scope resolution order-dependent.
+    expect(declare([{ name: 'CONNECTION_KEY', scope: 'user' }])).toEqual([]);
+    expect(declare([{ name: 'K', scope: 'user' }, { name: 'K', scope: 'admin' }])).toEqual([]);
+    const oauth = { tokenUrl: 'https://v.example/token', clientId: 'c' };
+    // Same https + SSRF gate the .tool parser runs on OAuth endpoints.
+    expect(declare([{ name: 'T', scope: 'user', oauth: { ...oauth, authorizationUrl: 'http://v.example/auth' } }])).toEqual([]);
+    expect(declare([{ name: 'T', scope: 'user', oauth: { ...oauth, authorizationUrl: 'https://169.254.169.254/auth' } }])).toEqual([]);
+    // authParams travel verbatim as query params — non-strings are malformed.
+    expect(
+      declare([{ name: 'T', scope: 'user', oauth: { ...oauth, authorizationUrl: 'https://v.example/auth', authParams: { p: 1 } } }]),
+    ).toEqual([]);
+    expect(
+      declare([{ name: 'T', scope: 'user', oauth: { ...oauth, authorizationUrl: 'https://v.example/auth', authParams: { p: 'x' } } }]),
+    ).toEqual(['vendor']);
+    // `clientId` must be non-empty after trimming, as in the `.tool` parser:
+    // a whitespace-only value would pass discovery only to fail the owner's
+    // client-secret setup later with "clientId is required".
+    expect(
+      declare([{ name: 'T', scope: 'user', oauth: { tokenUrl: 'https://v.example/token', authorizationUrl: 'https://v.example/auth', clientId: '   ' } }]),
+    ).toEqual([]);
+  });
+
+  it('trims a padded oauth clientId like the .tool parser does', () => {
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({ mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),
+      JSON.stringify({
+        name: 'gtm',
+        extensions: {
+          'software.bevel.hexis': {
+            mcpServers: {
+              vendor: {
+                variables: [
+                  {
+                    name: 'T',
+                    scope: 'user',
+                    oauth: { authorizationUrl: 'https://v.example/auth', tokenUrl: 'https://v.example/token', clientId: '  c-1  ' },
+                  },
+                ],
+              },
+            },
+          },
+        },
+      }),
+    );
+    expect(out[0]?.variables?.[0]?.oauth?.clientId).toBe('c-1');
+  });
+
+  it('yields nothing for an unparsable file, quietly for an absent extensions block', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(descriptorsFromMcpJson('GTM', '{ not json', null)).toEqual([]);
+    expect(
+      descriptorsFromMcpJson('GTM', JSON.stringify({ mcpServers: {} }), '{ also not json'),
+    ).toEqual([]);
+  });
+});

package/src/modules/tool-manuals/__tests__/mcp-server-edit.service.test.ts

@@ -0,0 +1,346 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_BRANCH, type AuthUser } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { IToolManualService, ToolManualSummary } from '../tool-manuals.contract.js';
+import { McpServerEditService } from '../mcp-server-edit.service.js';
+
+const KB = 'knowledge-base';
+const USER: AuthUser = { id: 'u-1', email: 'ali@example.com', name: 'Ali' } as AuthUser;
+
+let root: string;
+let repo: string;
+let svc: McpServerEditService;
+let commits: { runPendingCommit: ReturnType<typeof vi.fn> };
+let canWrite: boolean;
+let invalidated: number;
+
+/** Summaries the locate step reads — mirrors what mcp.json discovery yields. */
+const summaries: ToolManualSummary[] = [
+  { slug: 'vendor', name: 'vendor', path: 'Plugins/GTM/mcp.json', type: 'mcp' },
+  { slug: 'legacy', name: 'legacy', path: 'Plugins/GTM/software.bevel.hexis/tools/legacy.tool', type: 'mcp' },
+];
+
+async function write(rel: string, content: unknown): Promise<void> {
+  const abs = path.join(repo, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, JSON.stringify(content, null, 2), 'utf-8');
+}
+
+async function readJson(rel: string): Promise<Record<string, unknown>> {
+  return JSON.parse(await fs.readFile(path.join(repo, rel), 'utf-8'));
+}
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-mcp-edit-'));
+  const wsDir = path.join(root, workspaceIdForBranch(DEFAULT_BRANCH));
+  repo = path.join(wsDir, KB);
+  canWrite = true;
+  invalidated = 0;
+  commits = { runPendingCommit: vi.fn(async () => undefined) };
+
+  await write('Plugins/GTM/mcp.json', {
+    mcpServers: {
+      vendor: { type: 'streamable-http', url: 'https://v.example/mcp', headers: { 'X-V': '2' } },
+    },
+  });
+  await write('Plugins/GTM/plugin.json', {
+    name: 'gtm',
+    extensions: {
+      'software.bevel.hexis': {
+        mcpServers: {
+          vendor: {
+            headers: { Authorization: 'Bearer ${VENDOR_KEY}' },
+            variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+          },
+        },
+      },
+    },
+  });
+
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async () => ({ id: workspaceIdForBranch(DEFAULT_BRANCH) })),
+    getWorkspacePath: vi.fn(async () => wsDir),
+  } as unknown as WorkspaceService;
+  const accessControl = {
+    canWrite: vi.fn(async () => canWrite),
+  } as unknown as IAccessControl;
+  const toolManuals = {
+    listAccessible: vi.fn(async () => summaries),
+    invalidate: vi.fn(() => {
+      invalidated += 1;
+    }),
+  } as unknown as IToolManualService;
+
+  svc = new McpServerEditService(workspaceService, commits, accessControl, toolManuals, KB);
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe('getServer', () => {
+  it('merges both files into one view', async () => {
+    const view = await svc.getServer(USER.email, 'vendor');
+    expect(view).toMatchObject({
+      name: 'vendor',
+      transport: 'streamable-http',
+      url: 'https://v.example/mcp',
+      literalHeaders: { 'X-V': '2' },
+      authHeaders: { Authorization: 'Bearer ${VENDOR_KEY}' },
+      variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+      local: false,
+      canWrite: true,
+    });
+  });
+
+  it('shape-checks hand-editable fields — malformed values read as empty, not as nonsense', async () => {
+    await write('Plugins/GTM/plugin.json', {
+      name: 'gtm',
+      extensions: {
+        'software.bevel.hexis': {
+          // A string where an array/object belongs — the form would `.map`
+          // and `Object.entries` these; they must arrive as empty instead.
+          mcpServers: { vendor: { headers: 'oops', variables: 'not-an-array' } },
+        },
+      },
+    });
+    const view = await svc.getServer(USER.email, 'vendor');
+    expect(view?.variables).toEqual([]);
+    expect(view?.authHeaders).toEqual({});
+  });
+
+  it('answers null for an unknown slug and for a legacy .tool-backed manual alike', async () => {
+    expect(await svc.getServer(USER.email, 'nope')).toBeNull();
+    // A `.tool`-backed mcp manual predates the authoritative file; the form
+    // has no pair of files to edit for it, so it is not editable here.
+    expect(await svc.getServer(USER.email, 'legacy')).toBeNull();
+  });
+});
+
+describe('putServer', () => {
+  it('rewrites both files and commits the folder once', async () => {
+    await svc.putServer(USER, 'vendor', {
+      transport: 'streamable-http',
+      url: 'https://v2.example/mcp',
+      literalHeaders: { 'X-V': '3' },
+      authHeaders: { Authorization: 'Bearer ${VENDOR_KEY}' },
+      variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+    });
+    const mcp = await readJson('Plugins/GTM/mcp.json');
+    expect((mcp.mcpServers as Record<string, unknown>).vendor).toEqual({
+      type: 'streamable-http',
+      url: 'https://v2.example/mcp',
+      headers: { 'X-V': '3' },
+    });
+    expect(commits.runPendingCommit).toHaveBeenCalledTimes(1);
+    expect(commits.runPendingCommit).toHaveBeenCalledWith(
+      workspaceIdForBranch(DEFAULT_BRANCH),
+      DEFAULT_BRANCH,
+      `${KB}/Plugins/GTM`,
+      USER,
+    );
+    expect(invalidated).toBe(1);
+  });
+
+  it('reroutes a ${VAR} that arrives in the literal headers — mcp.json never carries one', async () => {
+    await svc.putServer(USER, 'vendor', {
+      transport: 'streamable-http',
+      url: 'https://v.example/mcp',
+      literalHeaders: { 'X-Key': '${SNEAKY}' },
+    });
+    const mcp = await readJson('Plugins/GTM/mcp.json');
+    expect((mcp.mcpServers as Record<string, { headers?: unknown }>).vendor.headers).toBeUndefined();
+    const manifest = await readJson('Plugins/GTM/plugin.json');
+    const ext = (manifest.extensions as Record<string, { mcpServers: Record<string, { headers?: unknown }> }>)[
+      'software.bevel.hexis'
+    ];
+    // The rerouted header lands BESIDE the stored auth (omitted, so kept) —
+    // rerouting must add to the extensions half, not replace it.
+    expect(ext.mcpServers.vendor.headers).toEqual({
+      Authorization: 'Bearer ${VENDOR_KEY}',
+      'X-Key': '${SNEAKY}',
+    });
+  });
+
+  it('renames across BOTH files, carrying every omitted field to the new key', async () => {
+    await svc.putServer(USER, 'vendor', {
+      newName: 'vendor_eu',
+      transport: 'streamable-http',
+      url: 'https://v.example/mcp',
+      authHeaders: { Authorization: 'Bearer ${VENDOR_KEY}' },
+    });
+    // FULL file contents, not just the key set: a rename that dropped the
+    // literal header or the variable declaration would still move the key.
+    const mcp = await readJson('Plugins/GTM/mcp.json');
+    expect(mcp.mcpServers).toEqual({
+      vendor_eu: {
+        type: 'streamable-http',
+        url: 'https://v.example/mcp',
+        headers: { 'X-V': '2' },
+      },
+    });
+    const manifest = await readJson('Plugins/GTM/plugin.json');
+    const servers = (
+      manifest.extensions as Record<string, { mcpServers: Record<string, unknown> }>
+    )['software.bevel.hexis'].mcpServers;
+    expect(servers).toEqual({
+      vendor_eu: {
+        headers: { Authorization: 'Bearer ${VENDOR_KEY}' },
+        variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+      },
+    });
+  });
+
+  it('preserves fields the write does not surface, and clears on explicit empties', async () => {
+    // Nothing surfaced beyond the transport: everything stored survives.
+    await svc.putServer(USER, 'vendor', { transport: 'streamable-http' });
+    let mcp = await readJson('Plugins/GTM/mcp.json');
+    expect((mcp.mcpServers as Record<string, unknown>).vendor).toEqual({
+      type: 'streamable-http',
+      url: 'https://v.example/mcp',
+      headers: { 'X-V': '2' },
+    });
+    let manifest = await readJson('Plugins/GTM/plugin.json');
+    let servers = (
+      manifest.extensions as Record<string, { mcpServers: Record<string, unknown> }>
+    )['software.bevel.hexis'].mcpServers;
+    expect(servers.vendor).toEqual({
+      headers: { Authorization: 'Bearer ${VENDOR_KEY}' },
+      variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+    });
+
+    // Present-but-empty is an explicit CLEAR, not an omission.
+    await svc.putServer(USER, 'vendor', {
+      transport: 'streamable-http',
+      literalHeaders: {},
+      authHeaders: {},
+      variables: [],
+    });
+    mcp = await readJson('Plugins/GTM/mcp.json');
+    expect((mcp.mcpServers as Record<string, unknown>).vendor).toEqual({
+      type: 'streamable-http',
+      url: 'https://v.example/mcp',
+    });
+    manifest = await readJson('Plugins/GTM/plugin.json');
+    servers = (
+      manifest.extensions as Record<string, { mcpServers: Record<string, unknown> }>
+    )['software.bevel.hexis'].mcpServers;
+    // An emptied extension entry is REMOVED, not left as `{}`.
+    expect(servers.vendor).toBeUndefined();
+  });
+
+  it('refuses a rename onto a taken key with 409, committing nothing', async () => {
+    // A second server occupies the target name.
+    const mcp = await readJson('Plugins/GTM/mcp.json');
+    (mcp.mcpServers as Record<string, unknown>).vendor_eu = {
+      type: 'streamable-http',
+      url: 'https://eu.example/mcp',
+    };
+    await fs.writeFile(path.join(repo, 'Plugins/GTM/mcp.json'), JSON.stringify(mcp), 'utf-8');
+    await expect(
+      svc.putServer(USER, 'vendor', { newName: 'vendor_eu', transport: 'streamable-http', url: 'https://v.example/mcp' }),
+    ).rejects.toMatchObject({ status: 409 });
+    expect(commits.runPendingCommit).not.toHaveBeenCalled();
+    // The original key survives untouched.
+    const after = await readJson('Plugins/GTM/mcp.json');
+    expect(Object.keys(after.mcpServers as object).sort()).toEqual(['vendor', 'vendor_eu']);
+  });
+
+  it('refuses without write access, an invalid name, and a bad URL', async () => {
+    canWrite = false;
+    await expect(
+      svc.putServer(USER, 'vendor', { transport: 'streamable-http', url: 'https://v.example' }),
+    ).rejects.toMatchObject({ status: 403 });
+    canWrite = true;
+    await expect(
+      svc.putServer(USER, 'vendor', { newName: 'Bad Name', transport: 'streamable-http', url: 'https://v.example' }),
+    ).rejects.toMatchObject({ status: 422 });
+    await expect(
+      svc.putServer(USER, 'vendor', { transport: 'streamable-http', url: 'not-a-url' }),
+    ).rejects.toMatchObject({ status: 422 });
+    expect(commits.runPendingCommit).not.toHaveBeenCalled();
+  });
+
+  it('422s a malformed variables declaration instead of persisting a server discovery will drop', async () => {
+    // Discovery's own validator, at save time: each of these shapes would
+    // save fine and then make the whole server vanish from the catalog on
+    // the next scan.
+    const bad: unknown[] = [
+      [{ name: 'bad name!', scope: 'user' }], // name outside [A-Za-z0-9_]+
+      [{ name: 'API_URL', scope: 'admin' }], // platform-seeded name re-declared
+      [{ name: 'K', scope: 'user' }, { name: 'K', scope: 'admin' }], // duplicate
+      [{ name: 'K', scope: 'team' }], // unknown scope
+      [
+        {
+          name: 'K',
+          scope: 'admin', // oauth demands per-caller scope
+          oauth: { authorizationUrl: 'https://v.example/auth', tokenUrl: 'https://v.example/token', clientId: 'c' },
+        },
+      ],
+      [
+        {
+          name: 'K',
+          scope: 'user', // whitespace-only clientId — same rule as discovery
+          oauth: { authorizationUrl: 'https://v.example/auth', tokenUrl: 'https://v.example/token', clientId: '   ' },
+        },
+      ],
+    ];
+    const before = await readJson('Plugins/GTM/plugin.json');
+    for (const variables of bad) {
+      await expect(
+        svc.putServer(USER, 'vendor', {
+          transport: 'streamable-http',
+          url: 'https://v.example/mcp',
+          variables: variables as never,
+        }),
+      ).rejects.toMatchObject({ status: 422 });
+    }
+    // Nothing landed: no commit, no file change.
+    expect(commits.runPendingCommit).not.toHaveBeenCalled();
+    expect(await readJson('Plugins/GTM/plugin.json')).toEqual(before);
+  });
+
+  it('422s malformed STORED variables on a save that never touched them — not a silent clear', async () => {
+    // A hand-edited plugin.json whose declarations went bad: coercing them
+    // to [] before validation would let any unrelated save erase them.
+    await write('Plugins/GTM/plugin.json', {
+      name: 'gtm',
+      extensions: {
+        'software.bevel.hexis': { mcpServers: { vendor: { variables: 'corrupt' } } },
+      },
+    });
+    const before = await readJson('Plugins/GTM/plugin.json');
+    await expect(
+      svc.putServer(USER, 'vendor', { transport: 'streamable-http', url: 'https://v.example/mcp' }),
+    ).rejects.toMatchObject({ status: 422 });
+    expect(commits.runPendingCommit).not.toHaveBeenCalled();
+    expect(await readJson('Plugins/GTM/plugin.json')).toEqual(before);
+    // Supplying valid declarations IS the repair path — that save lands.
+    await svc.putServer(USER, 'vendor', {
+      transport: 'streamable-http',
+      url: 'https://v.example/mcp',
+      variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+    });
+    expect(commits.runPendingCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it('writes a stdio entry with command/args and no url', async () => {
+    await svc.putServer(USER, 'vendor', {
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', 'indexer'],
+    });
+    const mcp = await readJson('Plugins/GTM/mcp.json');
+    expect((mcp.mcpServers as Record<string, unknown>).vendor).toEqual({
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', 'indexer'],
+    });
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.archive.route.test.ts

@@ -0,0 +1,101 @@
+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, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { createToolManualsAgentRoutes } from '../tool-manuals.routes.js';
+import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { IToolManualService } from '../tool-manuals.contract.js';
+
+/**
+ * `GET /agent/plugins/:folder/archive` — error taxonomy of the plugin-folder
+ * probe. An ABSENT folder is a 404; a folder the process cannot lstat
+ * (EACCES, EIO) is a real failure that must surface as a 500, because a 404
+ * would report a permission problem as "this plugin does not exist" and the
+ * caller would delete its local copy of a plugin that is still there.
+ */
+
+const KB = 'knowledge-base';
+
+let httpServer: HttpServer | undefined;
+let root: string;
+let wsDir: string;
+
+async function baseUrl(): Promise<string> {
+  const app = express();
+  const manualAuth: express.RequestHandler = (req, _res, next) => {
+    req.toolAuth = { userId: 'u-1' } as never;
+    next();
+  };
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async () => ({ id: workspaceIdForBranch(DEFAULT_BRANCH) })),
+    getWorkspacePath: vi.fn(async () => wsDir),
+  } as unknown as WorkspaceService;
+  const accessControl = {
+    canReadBatch: vi.fn(async (_ws: string, _email: string, rels: string[]) => {
+      return new Map(rels.map((r) => [r, true]));
+    }),
+  } as unknown as IAccessControl;
+  app.use(
+    '/api',
+    createToolManualsAgentRoutes(
+      {} as unknown as IToolManualService,
+      manualAuth,
+      async () => 'ali@example.com',
+      { workspaceService, accessControl, kbDirName: KB },
+    ),
+  );
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-archive-'));
+  wsDir = path.join(root, workspaceIdForBranch(DEFAULT_BRANCH));
+  await fs.mkdir(wsDir, { recursive: true });
+});
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+describe('GET /agent/plugins/:folder/archive', () => {
+  it('zips a readable plugin folder', async () => {
+    const pluginDir = path.join(wsDir, KB, 'Plugins', 'GTM');
+    await fs.mkdir(pluginDir, { recursive: true });
+    await fs.writeFile(path.join(pluginDir, 'web-search.tool'), '{"name":"web_search"}', 'utf-8');
+    const base = await baseUrl();
+    const res = await fetch(`${base}/api/agent/plugins/GTM/archive`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toContain('application/zip');
+  });
+
+  it('404s an absent plugin folder — ENOENT is an absence', async () => {
+    const base = await baseUrl();
+    const res = await fetch(`${base}/api/agent/plugins/Nope/archive`);
+    expect(res.status).toBe(404);
+    expect(await res.json()).toEqual({ error: 'Not found' });
+  });
+
+  it('500s when the folder probe fails for a non-ENOENT reason', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const denied: NodeJS.ErrnoException = Object.assign(new Error('EACCES: permission denied'), {
+      code: 'EACCES',
+    });
+    vi.spyOn(fs, 'lstat').mockRejectedValueOnce(denied);
+    const base = await baseUrl();
+    const res = await fetch(`${base}/api/agent/plugins/GTM/archive`);
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({ error: 'Failed to archive plugin' });
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.detail.route.test.ts

@@ -24,7 +24,7 @@ import type { IToolManualService, ToolManualDetail } from '../tool-manuals.contr
 const DETAIL: ToolManualDetail = {
   slug: 'github',
   name: 'github',
-  path: 'Groups/Engineering/github.tool',
+  path: 'Plugins/Engineering/github.tool',
   type: 'inline',
   description: 'Read and write GitHub issues and PRs.',
   capabilities: [{ name: 'create_issue', description: 'Open an issue in a repo.' }],
@@ -165,7 +165,7 @@ describe('ToolManualService.getDetail — capabilities + access', () => {
   /** Write one `.tool` into a fresh temp KB and return the service over it. */
   async function withTool(file: string, content: string): Promise<void> {
     root = await mkdtemp(join(tmpdir(), 'tooldetail-'));
-    const tools = join(root, wsId, KB_DIR, 'Groups');
+    const tools = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, file), content);
   }
@@ -189,7 +189,7 @@ describe('ToolManualService.getDetail — capabilities + access', () => {
     expect(detail).toMatchObject({
       slug: 'github',
       name: 'github',
-      path: 'Groups/github.tool',
+      path: 'Plugins/github.tool',
       type: 'inline',
       description: 'Read and write GitHub issues and PRs.',
       capabilities: [