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

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -50,14 +50,14 @@ describe('SkillService', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
-    const skills = join(root, wsId, KB_DIR, 'Groups');
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(join(skills, 'rfi', 'scripts'), { recursive: true });
     await writeFile(join(skills, 'rfi', 'SKILL.md'), RFI_SKILL);
     await writeFile(join(skills, 'rfi', 'scripts', 'build_xlsx.py'), 'print("xlsx")\n');
     // A folder with no SKILL.md is not a skill.
     await mkdir(join(skills, 'not-a-skill'), { recursive: true });
     await writeFile(join(skills, 'not-a-skill', 'README.md'), '# nope\n');
-    // A skill nested in a category subfolder (Groups/Development/coding-guidelines).
+    // A skill nested in a category subfolder (Plugins/Development/coding-guidelines).
     await mkdir(join(skills, 'Development', 'coding-guidelines'), { recursive: true });
     await writeFile(
       join(skills, 'Development', 'coding-guidelines', 'SKILL.md'),
@@ -72,7 +72,7 @@ describe('SkillService', () => {
     expect(skills).toHaveLength(2);
     const rfi = skills.find((s) => s.name === 'rfi')!;
     expect(rfi).toBeDefined();
-    expect(rfi.path).toBe('Groups/rfi');
+    expect(rfi.path).toBe('Plugins/rfi');
     expect(rfi.version).toBe('1.4.0');
     expect(rfi.description).not.toBe('|');
     expect(rfi.description).toContain('Specialist RFI responder');
@@ -83,19 +83,19 @@ describe('SkillService', () => {
     const skills = await svc().listSkills();
     const cg = skills.find((s) => s.name === 'coding-guidelines')!;
     expect(cg).toBeDefined();
-    expect(cg.path).toBe('Groups/Development/coding-guidelines');
+    expect(cg.path).toBe('Plugins/Development/coding-guidelines');
     expect(cg.description).toBe('Coding guidelines.');
 
     const res = await svc().getSkill('user@x.eu', 'coding-guidelines');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'skill') {
-      expect(res.skill.path).toBe('Groups/Development/coding-guidelines');
+      expect(res.skill.path).toBe('Plugins/Development/coding-guidelines');
       expect(res.skill.body).toContain('# Guidelines');
     }
   });
 
   test('refuses a colliding id (no auto-suffix) — the shared dedup rule', async () => {
-    const skills = join(root, wsId, KB_DIR, 'Groups');
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
     // Two skills resolve to the same id `dup` (no frontmatter id/name → folder name).
     await mkdir(join(skills, 'Zeta', 'dup'), { recursive: true });
     await writeFile(join(skills, 'Zeta', 'dup', 'SKILL.md'), '---\ndescription: zeta dup\n---\n\n# Z\n');
@@ -104,28 +104,28 @@ describe('SkillService', () => {
 
     const list = await svc().listSkills();
     // Only the first (smallest path) survives; the duplicate is dropped, not suffixed.
-    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Groups/Alpha/dup']);
+    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Plugins/Alpha/dup']);
     expect(list.find((s) => s.name === 'dup2')).toBeUndefined();
 
     const a = await svc().getSkill('user@x.eu', 'dup');
-    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Groups/Alpha/dup');
+    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Plugins/Alpha/dup');
   });
 
   test('frontmatter `id`/`name` overrides the folder name for identity', async () => {
-    const skills = join(root, wsId, KB_DIR, 'Groups');
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(join(skills, 'folderx'), { recursive: true });
     await writeFile(join(skills, 'folderx', 'SKILL.md'), '---\nid: my_skill\ndescription: d\n---\n\n# X\n');
     const list = await svc().listSkills();
-    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Groups/folderx');
+    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Plugins/folderx');
   });
 
   test('getSkill returns body, folder path, files and allowed-tools', async () => {
     const res = await svc().getSkill('user@x.eu', 'rfi');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'skill') {
-      expect(res.skill.path).toBe('Groups/rfi');
+      expect(res.skill.path).toBe('Plugins/rfi');
       expect(res.skill.body).toContain('# /rfi: Specialist RFI Responder');
-      expect(res.skill.files).toEqual(['Groups/rfi/scripts/build_xlsx.py']);
+      expect(res.skill.files).toEqual(['Plugins/rfi/scripts/build_xlsx.py']);
       expect(res.skill.allowedTools).toEqual(['Bash', 'Read']);
     }
   });
@@ -134,7 +134,7 @@ describe('SkillService', () => {
     const res = await svc().getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'file') {
-      expect(res.file.path).toBe('Groups/rfi/scripts/build_xlsx.py');
+      expect(res.file.path).toBe('Plugins/rfi/scripts/build_xlsx.py');
       expect(res.file.content).toContain('print("xlsx")');
     }
   });

package/src/modules/skills/pending-skills.service.ts

@@ -1,6 +1,6 @@
 import {
   DEFAULT_BRANCH,
-  GROUPS_DIR,
+  PLUGINS_DIR,
   type ChangeRequest,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
@@ -27,9 +27,9 @@ const SKILL_DOC = 'SKILL.md';
  *
  * WHO MAY SEE ONE is narrower than who may see the catalog: the author, and
  * whoever could approve it. "Could approve it" is not re-stated here as a
- * group-admin check — it is `canWrite` on the SKILL.md the request would
+ * plugin-admin check — it is `canWrite` on the SKILL.md the request would
  * create. The new folder carries no `access.md` of its own, so that verdict
- * inherits from the group folder, which IS the group's admin; asking the access
+ * inherits from the plugin folder, which IS the plugin's admin; asking the access
  * tree keeps this surface and the merge gate answering with one voice, and it
  * keeps working for skills nested in a category subfolder that carries rules of
  * its own.
@@ -80,7 +80,7 @@ export class PendingSkillsService implements IPendingSkillService {
     const authorHash = hashEmail(email);
 
     // One access load for every candidate. Resolved on the DEFAULT branch —
-    // the tree as it stands is what says who owns the group the skill is
+    // the tree as it stands is what says who owns the plugin the skill is
     // arriving into; the branch's own copy is written by the proposer and must
     // not get a say in who reviews them.
     const writable = await this.accessControl
@@ -148,16 +148,16 @@ export class PendingSkillsService implements IPendingSkillService {
 /**
  * Is this touched path a skill's own SKILL.md?
  *
- * `Groups/<group>/<skill>/SKILL.md` is the shallowest shape, hence four
+ * `Plugins/<plugin>/<skill>/SKILL.md` is the shallowest shape, hence four
  * segments; deeper ones are skills nested in a category subfolder, which the
- * catalog already supports. `Groups/<group>/SKILL.md` is NOT a skill — a group
+ * catalog already supports. `Plugins/<plugin>/SKILL.md` is NOT a skill — a plugin
  * folder is not itself one.
  */
 function isSkillDoc(repoRelPath: string): boolean {
   const segments = repoRelPath.split('/');
   return (
     segments.length >= 4 &&
-    segments[0] === GROUPS_DIR &&
+    segments[0] === PLUGINS_DIR &&
     segments[segments.length - 1] === SKILL_DOC
   );
 }

package/src/modules/skills/skills.contract.ts

@@ -1,5 +1,5 @@
 /**
- * Skills are reusable specialist instructions living under `Groups/<group>/<name>/SKILL.md`
+ * Skills are reusable specialist instructions living under `Plugins/<plugin>/<name>/SKILL.md`
  * in the KB repo. Discovery/loading is pinned to the DEFAULT branch — the catalog
  * is a single global, released set (a skill on a draft isn't discoverable until
  * merged). Progressive disclosure: `listSkills` = name + description (level 1),
@@ -12,7 +12,7 @@ export interface SkillSummary {
   name: string;
   description: string;
   version?: string;
-  /** Repo-root-relative skill folder, e.g. `Groups/Everyone/rfi`. */
+  /** Repo-root-relative skill folder, e.g. `Plugins/Everyone/rfi`. */
   path: string;
 }
 
@@ -21,7 +21,7 @@ export interface Skill extends SkillSummary {
   body: string;
   /** Pre-approved tools from the `allowed-tools` frontmatter, if declared. */
   allowedTools?: string[];
-  /** Repo-root-relative bundled file paths, e.g. `Groups/Everyone/rfi/scripts/build_xlsx.py`. */
+  /** Repo-root-relative bundled file paths, e.g. `Plugins/Everyone/rfi/scripts/build_xlsx.py`. */
   files: string[];
 }
 
@@ -48,7 +48,7 @@ export type GetSkillResult =
  *
  * Who may see one is narrower than who may see the catalog: its author, and
  * whoever could approve it. See `PendingSkillsService` for why that predicate
- * is the access tree's answer rather than a group-admin check spelled out
+ * is the access tree's answer rather than a plugin-admin check spelled out
  * again here.
  */
 export interface PendingSkill extends SkillSummary {

package/src/modules/skills/skills.service.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import { parseDocument } from 'yaml';
-import { DEFAULT_BRANCH, GROUPS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -103,8 +103,8 @@ export class SkillService implements ISkillService {
   }
 
   private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Groups/ dir. Any
-    // failure (no workspace, no Groups/ dir) degrades to an empty catalog — the
+    // Ensure the default-branch clone exists, then scan its Plugins/ dir. Any
+    // failure (no workspace, no Plugins/ dir) degrades to an empty catalog — the
     // manual/tools must never break because skills can't be read.
     let wsId: string;
     try {
@@ -119,7 +119,7 @@ export class SkillService implements ISkillService {
     // tree and treat every folder that directly contains a SKILL.md as a skill;
     // don't descend past it — its inner files are bundled assets, not nested
     // skills. The skill name is the leaf folder name; its path is the full
-    // repo-relative folder (e.g. `Groups/Development/coding-guidelines`).
+    // repo-relative folder (e.g. `Plugins/Development/coding-guidelines`).
     const out: ParsedSkill[] = [];
     const walk = async (dir: string, relFolder: string): Promise<void> => {
       let entries: import('node:fs').Dirent[];
@@ -156,7 +156,7 @@ export class SkillService implements ISkillService {
         await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
       }
     };
-    await walk(path.join(kbRoot, GROUPS_DIR), GROUPS_DIR);
+    await walk(path.join(kbRoot, PLUGINS_DIR), PLUGINS_DIR);
     // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
     // resolves it, so it must be unique. Sort by (name, path) for a deterministic
     // winner, then REFUSE later duplicates via the shared dedup — the same rule

package/src/modules/tool-auth/llm-usage-meter.ts

@@ -1,19 +1,19 @@
-/**
- * Metering view over connection-key LLM usage, consumed by the connection-key
- * management routes (mcp) to show each key's spend against the daily budget.
- * The enterprise LLM proxy's `LlmUsageService` satisfies this structurally; a
- * core-only deployment (no LLM proxy, nothing to meter) passes
- * {@link unmeteredLlmUsage}.
- */
-export interface ILlmUsageMeter {
-  /** Daily per-key token cap shown in the UI, or null when unmetered. */
-  readonly dailyCap: number | null;
-  /** Today's usage per key id, as `{ [tokenId]: tokens }` — missing keys mean 0. */
-  usageForTokens(tokenIds: string[]): Promise<Record<string, number>>;
-}
-
-/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
-export const unmeteredLlmUsage: ILlmUsageMeter = {
-  dailyCap: null,
-  usageForTokens: async () => ({}),
-};
+/**
+ * Metering view over connection-key LLM usage, consumed by the connection-key
+ * management routes (mcp) to show each key's spend against the daily budget.
+ * The enterprise LLM proxy's `LlmUsageService` satisfies this structurally; a
+ * core-only deployment (no LLM proxy, nothing to meter) passes
+ * {@link unmeteredLlmUsage}.
+ */
+export interface ILlmUsageMeter {
+  /** Daily per-key token cap shown in the UI, or null when unmetered. */
+  readonly dailyCap: number | null;
+  /** Today's usage per key id, as `{ [tokenId]: tokens }` — missing keys mean 0. */
+  usageForTokens(tokenIds: string[]): Promise<Record<string, number>>;
+}
+
+/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
+export const unmeteredLlmUsage: ILlmUsageMeter = {
+  dailyCap: null,
+  usageForTokens: async () => ({}),
+};

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([]);
+  });
+});