@bevel-software/platform-core-backend 0.4.0 → 0.5.0

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

@@ -0,0 +1,168 @@
+import {
+  DEFAULT_BRANCH,
+  GROUPS_DIR,
+  type ChangeRequest,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import { workspaceIdForBranch, type WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { hashEmail } from '../../shared/hash-email.js';
+import { resolveDeclaredId } from '../../shared/frontmatter-id.js';
+import { isSafeSkillName, parseSkillFrontmatter } from './skills.service.js';
+import type { IPendingSkillService, ISkillService, PendingSkill } from './skills.contract.js';
+
+const SKILL_DOC = 'SKILL.md';
+
+/**
+ * Skills that exist only on an open change request — proposed, not released.
+ *
+ * The catalog (`SkillService`) is pinned to the default branch, which is the
+ * right answer for everything that LOADS a skill and the wrong one for the
+ * person who just proposed it: a change request that ADDS a skill folder has
+ * nothing on the default branch to hang itself off, so until it merged the
+ * proposal was invisible to its author and to the people who had to approve it.
+ * This service is that missing half, and it is deliberately a separate surface
+ * rather than a widening of the catalog — an unapproved skill must never become
+ * loadable just because it became visible.
+ *
+ * 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
+ * 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
+ * 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.
+ *
+ * Everything degrades to "nothing pending" rather than throwing: this hangs off
+ * the library's list load, and a review surface that cannot answer must not
+ * take the shelf down with it.
+ */
+export class PendingSkillsService implements IPendingSkillService {
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly accessControl: IAccessControl,
+    private readonly skillService: ISkillService,
+    private readonly workflow: IWorkflowService,
+  ) {}
+
+  async listPendingSkills(userEmail: string): Promise<PendingSkill[]> {
+    const email = userEmail.trim().toLowerCase();
+    if (!email) return [];
+
+    let crs: ChangeRequest[];
+    try {
+      crs = (await this.workflow.listChangeRequests()).filter((c) => c.state === 'open');
+    } catch {
+      return [];
+    }
+    if (crs.length === 0) return [];
+
+    // The released set, UNFILTERED by the caller's read access. A skill someone
+    // else can read and this caller cannot is still released — counting it as
+    // pending would invent a review that is not happening, and would leak the
+    // fact that the folder exists.
+    let released: Set<string>;
+    try {
+      released = new Set((await this.skillService.listSkills()).map((s) => s.path));
+    } catch {
+      return [];
+    }
+
+    const candidates = crs.flatMap((cr) =>
+      cr.touchedNodePaths
+        .filter((p) => isSkillDoc(p) && !released.has(folderOf(p)))
+        .map((p) => ({ cr, docPath: p, folder: folderOf(p) })),
+    );
+    if (candidates.length === 0) return [];
+
+    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    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
+    // 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
+      .canWriteBatch(
+        wsId,
+        email,
+        candidates.map((c) => c.docPath),
+      )
+      .catch(() => new Map<string, boolean>());
+
+    // The branch copies are read through the default branch's clone at
+    // `origin/<branch>`, so a proposal never needs a clone of its own. Refresh
+    // first, best-effort: a request pushed seconds ago is worth one fetch, and
+    // a failed fetch should degrade to "read what we have".
+    await this.workspaceService.ensureRemotesFetched(wsId).catch(() => undefined);
+
+    const out: PendingSkill[] = [];
+    for (const { cr, docPath, folder } of candidates) {
+      const isAuthor = !!cr.authorId && cr.authorId === authorHash;
+      // Fail closed, matching the catalog: only an explicit `true` admits a
+      // reviewer. A missing entry (the batch skipped the path, the tree could
+      // not be read) means denied, never shown.
+      if (!isAuthor && writable.get(docPath) !== true) continue;
+
+      const raw = await this.readAt(wsId, cr.branch, docPath);
+      // Nothing to describe: the request touched the path but the file is gone
+      // at its head (proposed then withdrawn within the branch), or unreadable.
+      if (raw === null) continue;
+
+      const fm = parseSkillFrontmatter(raw);
+      const folderName = folder.split('/').pop() ?? folder;
+      const declared = resolveDeclaredId(fm.frontmatter, folderName);
+      out.push({
+        name: isSafeSkillName(declared) ? declared : folderName,
+        description: fm.description,
+        version: fm.version,
+        path: folder,
+        changeRequestNumber: cr.number,
+        branch: cr.branch,
+        authorName: cr.appAuthor?.name ?? cr.author.name ?? 'Someone',
+        createdAt: cr.createdAt,
+        isAuthor,
+      });
+    }
+    // Oldest first — the one that has been waiting longest is the one that
+    // needs answering, and a list that reorders as requests arrive moves under
+    // the pointer.
+    return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+
+  /** The file at a branch, or null when it is absent/unreadable there. */
+  private async readAt(
+    wsId: string,
+    branch: string,
+    repoRelPath: string,
+  ): Promise<string | null> {
+    try {
+      return await this.workspaceService.readFileAtRef(wsId, `origin/${branch}`, repoRelPath);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Is this touched path a skill's own SKILL.md?
+ *
+ * `Groups/<group>/<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
+ * folder is not itself one.
+ */
+function isSkillDoc(repoRelPath: string): boolean {
+  const segments = repoRelPath.split('/');
+  return (
+    segments.length >= 4 &&
+    segments[0] === GROUPS_DIR &&
+    segments[segments.length - 1] === SKILL_DOC
+  );
+}
+
+/** The skill folder holding a SKILL.md. */
+function folderOf(skillDocPath: string): string {
+  return skillDocPath.slice(0, -(SKILL_DOC.length + 1));
+}

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

@@ -1,5 +1,5 @@
 /**
- * Skills are reusable specialist instructions living under `Skills/<name>/SKILL.md`
+ * Skills are reusable specialist instructions living under `Groups/<group>/<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. `Skills/rfi`. */
+  /** Repo-root-relative skill folder, e.g. `Groups/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. `Skills/rfi/scripts/build_xlsx.py`. */
+  /** Repo-root-relative bundled file paths, e.g. `Groups/Everyone/rfi/scripts/build_xlsx.py`. */
   files: string[];
 }
 
@@ -40,6 +40,37 @@ export type GetSkillResult =
   | { ok: true; kind: 'file'; file: SkillFileContent }
   | { ok: false; error: 'not_found' | 'forbidden' | 'invalid_file' };
 
+/**
+ * A skill that exists ONLY on an open change request's branch — proposed, not
+ * released. It is deliberately NOT a `SkillSummary` the catalog returns: the
+ * catalog is what agents load, and a skill nobody has approved must not be
+ * loadable. This is a review surface only.
+ *
+ * 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
+ * again here.
+ */
+export interface PendingSkill extends SkillSummary {
+  /** The open change request that would release it. */
+  changeRequestNumber: number;
+  branch: string;
+  /** Display name of whoever opened the request (person or agent). */
+  authorName: string;
+  createdAt: string;
+  /** True when the caller opened the request themselves. */
+  isAuthor: boolean;
+}
+
+export interface IPendingSkillService {
+  /**
+   * Skills awaiting approval that `userEmail` is entitled to see — the ones
+   * they proposed, and the ones they could approve. Never throws: a review
+   * surface failing must not take the library down with it.
+   */
+  listPendingSkills(userEmail: string): Promise<PendingSkill[]>;
+}
+
 export interface ISkillService {
   /**
    * The default-branch skill catalog. When `userEmail` is given, filtered to

package/src/modules/skills/skills.routes.ts

@@ -1,6 +1,6 @@
 import express from 'express';
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import type { ISkillService } from './skills.contract.js';
+import type { IPendingSkillService, ISkillService } from './skills.contract.js';
 
 /**
  * Browser-facing (JWT) skill routes for the `/`-command menu, mounted behind
@@ -9,10 +9,14 @@ import type { ISkillService } from './skills.contract.js';
  * ONCE — the frontend never re-implements skill discovery or bypasses access.
  *
  *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user)
+ *   GET /api/skills/pending    → { skills: PendingSkill[] }   (proposed, not released)
  *   GET /api/skills/:name      → GetSkillResult               (body + files)
  *   GET /api/skills/:name?file=… → GetSkillResult             (a bundled file's content)
  */
-export function createSkillsRoutes(skillService: ISkillService): express.Router {
+export function createSkillsRoutes(
+  skillService: ISkillService,
+  pendingSkills?: IPendingSkillService,
+): express.Router {
   const router = express.Router();
 
   router.get('/skills', async (req, res) => {
@@ -24,6 +28,23 @@ export function createSkillsRoutes(skillService: ISkillService): express.Router
     res.json({ skills: await skillService.listSkills(email) });
   });
 
+  /**
+   * BEFORE `/skills/:name`, and it has to stay there: Express matches in
+   * declaration order, so the parameterised route would otherwise swallow
+   * `pending` and answer "no such skill".
+   *
+   * Optional dependency so a host that composes its own service set gets an
+   * empty review shelf rather than a 404 the frontend has to special-case.
+   */
+  router.get('/skills/pending', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    res.json({ skills: pendingSkills ? await pendingSkills.listPendingSkills(email) : [] });
+  });
+
   router.get('/skills/:name', async (req, res) => {
     const email = req.userEmail;
     if (!email) {

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, SKILLS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, GROUPS_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';
@@ -63,7 +63,7 @@ export class SkillService implements ISkillService {
   }
 
   async getSkill(userEmail: string, name: string, file?: string): Promise<GetSkillResult> {
-    if (!isSafeName(name)) return { ok: false, error: 'not_found' };
+    if (!isSafeSkillName(name)) return { ok: false, error: 'not_found' };
     const found = (await this.scan()).find((s) => s.summary.name === name);
     if (!found) return { ok: false, error: 'not_found' };
 
@@ -103,8 +103,8 @@ export class SkillService implements ISkillService {
   }
 
   private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Skills/ dir. Any
-    // failure (no workspace, no Skills/ dir) degrades to an empty catalog — the
+    // Ensure the default-branch clone exists, then scan its Groups/ dir. Any
+    // failure (no workspace, no Groups/ dir) degrades to an empty catalog — the
     // manual/tools must never break because skills can't be read.
     let wsId: string;
     try {
@@ -112,18 +112,14 @@ export class SkillService implements ISkillService {
     } catch {
       return [];
     }
-    const root = path.join(
-      await this.workspaceService.getWorkspacePath(wsId),
-      this.kbDirName,
-      SKILLS_DIR,
-    );
+    const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
     // Skills may be grouped in category subfolders (each carrying its own
-    // access.md), so a SKILL.md can live at any depth under Skills/. Walk the
+    // access.md), so a SKILL.md can live at any depth under the root. Walk the
     // 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
-    // Skills-relative folder (e.g. `Skills/Development/coding-guidelines`).
+    // repo-relative folder (e.g. `Groups/Development/coding-guidelines`).
     const out: ParsedSkill[] = [];
     const walk = async (dir: string, relFolder: string): Promise<void> => {
       let entries: import('node:fs').Dirent[];
@@ -146,7 +142,7 @@ export class SkillService implements ISkillService {
         // fall back to the folder name (a readdir entry, safe by construction)
         // to keep listing and lookup consistent.
         const declared = resolveDeclaredId(fm.frontmatter, path.basename(dir));
-        const name = isSafeName(declared) ? declared : path.basename(dir);
+        const name = isSafeSkillName(declared) ? declared : path.basename(dir);
         out.push({
           summary: { name, description: fm.description, version: fm.version, path: relFolder },
           body: fm.body,
@@ -160,7 +156,7 @@ export class SkillService implements ISkillService {
         await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
       }
     };
-    await walk(root, SKILLS_DIR);
+    await walk(path.join(kbRoot, GROUPS_DIR), GROUPS_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
@@ -181,8 +177,14 @@ export class SkillService implements ISkillService {
 
 // --- helpers ------------------------------------------------------------------
 
-/** Skill names are folder names; reject anything that could escape the folder. */
-function isSafeName(name: string): boolean {
+/**
+ * Skill names are folder names; reject anything that could escape the folder.
+ *
+ * Exported because the pending-skill surface resolves a name from a SKILL.md
+ * that is not on disk yet and must land on the SAME id the catalog will give it
+ * once merged — a second copy of this rule would drift.
+ */
+export function isSafeSkillName(name: string): boolean {
   return name.length > 0 && !name.includes('/') && !name.includes('\\') && name !== '.' && name !== '..';
 }
 
@@ -198,7 +200,13 @@ function scalarToString(value: unknown): string | undefined {
   return undefined;
 }
 
-function parseSkillFrontmatter(raw: string): {
+/**
+ * Exported for the pending-skill surface, which parses a SKILL.md read at a
+ * change request's ref rather than off disk. Same parser deliberately: a
+ * proposed skill must be described by the same rules that will describe it once
+ * it is released, or the card in review and the card after approval disagree.
+ */
+export function parseSkillFrontmatter(raw: string): {
   description: string;
   version?: string;
   allowedTools?: string[];

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

@@ -0,0 +1,262 @@
+import type { Server as HttpServer } from 'node:http';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express from 'express';
+import { afterEach, describe, expect, it, test, vi } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { createToolManualsBrowserRoutes } from '../tool-manuals.routes.js';
+import { ToolManualService } from '../tool-manuals.service.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, ToolManualDetail } from '../tool-manuals.contract.js';
+
+/**
+ * `GET /api/tools/:slug` — the browser tool page's detail read. Two halves:
+ * the ROUTE (auth gating + the fail-closed 404, over a stub service on a real
+ * loopback server, the harness style the other route tests use) and the
+ * SERVICE's capability derivation (over a real temp KB, because deriving
+ * capabilities from author-written `tools` is the only logic here worth
+ * testing and a stub would test nothing).
+ */
+
+const DETAIL: ToolManualDetail = {
+  slug: 'github',
+  name: 'github',
+  path: 'Groups/Engineering/github.tool',
+  type: 'inline',
+  description: 'Read and write GitHub issues and PRs.',
+  capabilities: [{ name: 'create_issue', description: 'Open an issue in a repo.' }],
+};
+
+let httpServer: HttpServer | undefined;
+
+/** Mount the browser routes behind a fake auth middleware; `email` undefined ⇒ unauthenticated. */
+async function baseUrlAs(
+  email: string | undefined,
+  getDetail: IToolManualService['getDetail'],
+): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    if (email) req.userEmail = email;
+    next();
+  });
+  const toolManualService = { getDetail } as unknown as IToolManualService;
+  app.use('/api', createToolManualsBrowserRoutes(toolManualService));
+  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}`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+});
+
+describe('GET /api/tools/:slug — route', () => {
+  it('returns 200 { tool } with description and capabilities for a readable tool', async () => {
+    const base = await baseUrlAs('reader@x.com', async () => DETAIL);
+    const res = await fetch(`${base}/api/tools/github`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ tool: DETAIL });
+  });
+
+  it('passes the caller email and the slug through to the service', async () => {
+    const getDetail = vi.fn(async () => DETAIL);
+    const base = await baseUrlAs('reader@x.com', getDetail);
+    await fetch(`${base}/api/tools/github`);
+    expect(getDetail).toHaveBeenCalledWith('reader@x.com', 'github');
+  });
+
+  it('404s an unknown slug', async () => {
+    const base = await baseUrlAs('reader@x.com', async () => null);
+    const res = await fetch(`${base}/api/tools/nope`);
+    expect(res.status).toBe(404);
+    expect(await res.json()).toEqual({ error: 'Not found' });
+  });
+
+  it('404s — identically — a tool the caller cannot read', async () => {
+    // Fail-closed: a caller without read access gets the SAME response an
+    // absent slug produces, so a 404 can never confirm a hidden tool exists.
+    const unreadable = await baseUrlAs('outsider@x.com', async () => null);
+    const unknownRes = await fetch(`${unreadable}/api/tools/github`);
+    expect(unknownRes.status).toBe(404);
+    expect(await unknownRes.json()).toEqual({ error: 'Not found' });
+  });
+
+  it('401s without an authenticated email', async () => {
+    const getDetail = vi.fn(async () => DETAIL);
+    const base = await baseUrlAs(undefined, getDetail);
+    const res = await fetch(`${base}/api/tools/github`);
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: 'Not authenticated' });
+    expect(getDetail).not.toHaveBeenCalled(); // never even asks the service
+  });
+
+  it('500s with a generic message when the service throws', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const base = await baseUrlAs('reader@x.com', async () => {
+      throw new Error('disk on fire');
+    });
+    const res = await fetch(`${base}/api/tools/github`);
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({ error: 'Failed to load tool' });
+  });
+
+  it('does not shadow the literal POST /tools/preview sibling', async () => {
+    // The param route is GET-only, so the draft-validation route still gets its
+    // own POSTs — the one registration-order hazard this route introduces.
+    const preview = vi.fn(async () => ({ ok: true }));
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userEmail = 'reader@x.com';
+      next();
+    });
+    app.use(
+      '/api',
+      createToolManualsBrowserRoutes({
+        getDetail: async () => DETAIL,
+        preview,
+      } as unknown as IToolManualService),
+    );
+    httpServer = await new Promise<HttpServer>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const port = (httpServer.address() as { port: number }).port;
+    const res = await fetch(`http://127.0.0.1:${port}/api/tools/preview`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ content: '{}' }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+    expect(preview).toHaveBeenCalledWith('{}');
+  });
+});
+
+describe('ToolManualService.getDetail — capabilities + access', () => {
+  const KB_DIR = 'knowledge-base';
+  const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+  let root: string;
+
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+
+  const allowAll: IAccessControl = {
+    canRead: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+
+  const denyAll: IAccessControl = {
+    canRead: async () => false,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
+  } as unknown as IAccessControl;
+
+  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, KB_DIR);
+
+  /** 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');
+    await mkdir(tools, { recursive: true });
+    await writeFile(join(tools, file), content);
+  }
+
+  afterEach(() => rm(root, { recursive: true, force: true }));
+
+  test('an inline tool reports its description and its embedded tools as capabilities', async () => {
+    await withTool(
+      'github.tool',
+      JSON.stringify({
+        name: 'github',
+        type: 'inline',
+        description: '  Read and write GitHub issues and PRs.  ',
+        tools: [
+          { name: 'create_issue', description: 'Open an issue in a repo.' },
+          { name: 'list_prs' }, // no description → null, still a capability
+        ],
+      }),
+    );
+    const detail = await svc().getDetail('user@x.eu', 'github');
+    expect(detail).toMatchObject({
+      slug: 'github',
+      name: 'github',
+      path: 'Groups/github.tool',
+      type: 'inline',
+      description: 'Read and write GitHub issues and PRs.',
+      capabilities: [
+        { name: 'create_issue', description: 'Open an issue in a repo.' },
+        { name: 'list_prs', description: null },
+      ],
+    });
+  });
+
+  test('description is null (not undefined) when the file declares none', async () => {
+    await withTool('bare.tool', JSON.stringify({ name: 'bare', type: 'inline', tools: [] }));
+    const detail = await svc().getDetail('user@x.eu', 'bare');
+    expect(detail?.description).toBeNull();
+    expect(detail?.capabilities).toEqual([]);
+  });
+
+  test('http and mcp manuals report no capabilities (their tools resolve at call time)', async () => {
+    await withTool('billing.tool', JSON.stringify({ name: 'billing', type: 'http', url: 'https://api.example.com/utcp' }));
+    expect((await svc().getDetail('user@x.eu', 'billing'))?.capabilities).toEqual([]);
+    await withTool('remote.tool', JSON.stringify({ name: 'remote', type: 'mcp', url: 'https://mcp.example.com/mcp' }));
+    expect((await svc().getDetail('user@x.eu', 'remote'))?.capabilities).toEqual([]);
+  });
+
+  test('malformed `tools` entries are skipped, not rendered as blank bullets', async () => {
+    // `tools` is `unknown[]` — only validated when actually served as a UTCP
+    // manual — so the page's derivation has to re-check every entry itself.
+    await withTool(
+      'messy.tool',
+      JSON.stringify({
+        name: 'messy',
+        type: 'inline',
+        tools: [
+          null,
+          'just a string',
+          ['an', 'array'],
+          { description: 'nameless' },
+          { name: 42 },
+          { name: '   ' },
+          { name: 'ok', description: 7 }, // non-string description → null
+          { name: 'fine', description: 'Works.' },
+        ],
+      }),
+    );
+    expect((await svc().getDetail('user@x.eu', 'messy'))?.capabilities).toEqual([
+      { name: 'ok', description: null },
+      { name: 'fine', description: 'Works.' },
+    ]);
+  });
+
+  test('caps capabilities at 100 so one `.tool` cannot produce an unbounded page', async () => {
+    await withTool(
+      'many.tool',
+      JSON.stringify({
+        name: 'many',
+        type: 'inline',
+        tools: Array.from({ length: 150 }, (_, i) => ({ name: `t${i}` })),
+      }),
+    );
+    const caps = (await svc().getDetail('user@x.eu', 'many'))!.capabilities;
+    expect(caps).toHaveLength(100);
+    expect(caps[0].name).toBe('t0');
+    expect(caps[99].name).toBe('t99');
+  });
+
+  test('returns null for an unknown slug and for a tool the caller cannot read', async () => {
+    await withTool('github.tool', JSON.stringify({ name: 'github', type: 'inline', tools: [] }));
+    expect(await svc().getDetail('user@x.eu', 'nosuchtool')).toBeNull();
+    expect(await svc(denyAll).getDetail('user@x.eu', 'github')).toBeNull();
+  });
+});

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

@@ -46,7 +46,7 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'tools-oauth-'));
-    const toolsDir = join(root, wsId, KB_DIR, 'Tools');
+    const toolsDir = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(toolsDir, { recursive: true });
     await writeFile(join(toolsDir, 'notion.tool'), BARE_MCP_TOOL);
     await writeFile(join(toolsDir, 'jira.tool'), KEYED_MCP_TOOL);
@@ -109,7 +109,7 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
   });
 
   test('referenced-but-undeclared ${VAR}s are auto-surfaced as admin keys (any tool type)', async () => {
-    const toolsDir = join(root, wsId, KB_DIR, 'Tools');
+    const toolsDir = join(root, wsId, KB_DIR, 'Groups');
     await writeFile(
       join(toolsDir, 'billing.tool'),
       JSON.stringify({