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

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -1,7 +1,15 @@
 import express, { type Request, type RequestHandler } from 'express';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import AdmZip from 'adm-zip';
+import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch, type WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
 import '@utcp/http'; // side effect: register the 'http' call-template type
 import { CallTemplateSerializer, type CallTemplate } from '@utcp/sdk';
 import { type IToolManualService, EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
+import { McpServerEditError, type McpServerEditService, type McpServerWrite } from './mcp-server-edit.service.js';
+import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
 import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
 
@@ -35,6 +43,7 @@ export function createToolManualsAgentRoutes(
   toolManualService: IToolManualService,
   manualAuth: RequestHandler,
   resolveUserEmail: ResolveUserEmail,
+  archiveDeps?: { workspaceService: WorkspaceService; accessControl: IAccessControl; kbDirName: string },
 ): express.Router {
   const router = express.Router();
 
@@ -63,6 +72,173 @@ export function createToolManualsAgentRoutes(
     }
   });
 
+  /**
+   * The whole plugin, byte-for-byte, as a zip — the materialization surface
+   * for the local MCP server. `read_file` is the agent's READING tool (text,
+   * one file at a time); this exists because a stdio server's plugin must
+   * land on the user's disk exactly as it is, binaries included. Access is
+   * per-file and the caller's own: every entry is filtered through the same
+   * read verdicts `list_files` uses, so a file the key cannot read is a file
+   * that is not in the archive — not an error, an absence.
+   */
+  router.get('/agent/plugins/:folder/archive', manualAuth, async (req, res) => {
+    if (!archiveDeps) return void res.status(404).json({ error: 'Not available' });
+    try {
+      const email = await callerEmail(req);
+      if (!email) return void res.status(403).json({ error: 'Forbidden' });
+      const folder = String(Array.isArray(req.params.folder) ? req.params.folder[0] : req.params.folder);
+      if (!folder || folder === '.' || folder === '..' || /[/\\]/.test(folder)) {
+        return void res.status(422).json({ error: 'Not a plugin folder name' });
+      }
+      const { workspaceService, accessControl, kbDirName } = archiveDeps;
+      const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+      await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+      const wsDir = await workspaceService.getWorkspacePath(wsId);
+      const pluginDir = path.join(wsDir, kbDirName, PLUGINS_DIR, folder);
+      // SYMLINKS ARE NOT SUPPORTED IN PLUGINS, anywhere. Access control
+      // resolves rules by path, and a symlink is a second path to the same
+      // content — a standing invitation for the spelling the ACL judged and
+      // the bytes served to diverge. The platform's own write paths never
+      // create one (they arrive only via direct git pushes), so every symlink
+      // is skipped rather than resolved: no target following, no cycle
+      // guards, no read-time re-resolution — complexity that existed only to
+      // support what the platform has no use for. Starting with the plugin
+      // folder itself: a symlinked `Plugins/<folder>` is not a plugin.
+      // Only ENOENT is an absence; an EACCES/EIO answered with 404 would
+      // dress a real read problem up as a missing plugin (the same contract
+      // as the realpath/open probes below).
+      const folderStat = await fs.lstat(pluginDir).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+      });
+      if (folderStat === null || !folderStat.isDirectory()) {
+        return void res.status(404).json({ error: 'Not found' });
+      }
+      const rels: string[] = [];
+      const walk = async (dir: string, rel: string): Promise<void> => {
+        let entries;
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch (err) {
+          // Only an absent directory is a non-event; anything else (EACCES,
+          // EIO) silently missing from the archive would hand the client an
+          // incomplete plugin stamped as success.
+          if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
+          throw err;
+        }
+        for (const e of entries) {
+          if (e.name === '.git') continue;
+          const childRel = rel ? `${rel}/${e.name}` : e.name;
+          // Dirent's isDirectory/isFile are both false for a symlink, so a
+          // link is never walked and never listed — but say so, once, because
+          // an author who committed one deserves to know it went nowhere.
+          if (e.isDirectory()) await walk(path.join(dir, e.name), childRel);
+          else if (e.isFile()) rels.push(childRel);
+          else if (e.isSymbolicLink()) {
+            console.warn(`[tool-manuals] archive of "${folder}": ${childRel} is a symlink — not supported in plugins, skipped.`);
+          }
+        }
+      };
+      await walk(pluginDir, '');
+      if (rels.length === 0) return void res.status(404).json({ error: 'Not found' });
+      const verdicts = await accessControl.canReadBatch(
+        wsId,
+        email,
+        rels.map((r) => `${PLUGINS_DIR}/${folder}/${r}`),
+      );
+      const zip = new AdmZip();
+      let included = 0;
+      let bytes = 0;
+      // The zip is built in memory; without a ceiling one plugin full of large
+      // assets is a backend OOM any key holder can trigger.
+      const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+      // Canonical base for the read-time identity check below. The folder was
+      // lstat-verified a real directory above, so this is normalization
+      // (case, 8.3 names, drive spelling), not link resolution — but that
+      // verification is a moment old, and a plugin deleted since (a workspace
+      // reset, a merged deletion) is an ABSENCE, the same 404 it would have
+      // been a moment earlier, not an internal error.
+      const pluginRealBase = await fs.realpath(pluginDir).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+      });
+      if (pluginRealBase === null) return void res.status(404).json({ error: 'Not found' });
+      for (const rel of rels) {
+        // Fail closed, per file — only an explicit `true` verdict is included.
+        if (verdicts.get(`${PLUGINS_DIR}/${folder}/${rel}`) !== true) continue;
+        const abs = path.join(pluginDir, ...rel.split('/'));
+        // The no-symlink rule, re-checked at read time over the WHOLE path.
+        // The open below guards only the final component — a PARENT directory
+        // swapped for a link between walk and read makes `abs` traverse the
+        // link with the final component still a regular file. realpath
+        // resolves every component, so demanding it equal the spelled path is
+        // exactly "no component is a link": identity, not mere containment.
+        const realNow = await fs.realpath(abs).catch((err: NodeJS.ErrnoException) => {
+          if (err.code === 'ENOENT') return null; // deleted since the walk — an absence, not a failure
+          throw err;
+        });
+        if (realNow === null || realNow !== path.join(pluginRealBase, ...rel.split('/'))) {
+          if (realNow !== null) {
+            console.warn(`[tool-manuals] archive of "${folder}": ${rel} no longer resolves to itself — skipped.`);
+          }
+          continue;
+        }
+        // Check and read through ONE file handle, so the bytes that land in
+        // the zip come from the very inode the checks passed — a path-based
+        // stat-then-readFile pair leaves a window where the path is swapped
+        // between the two and the archive ships bytes the ACL never judged.
+        // O_NOFOLLOW makes a final-component symlink fail the open itself
+        // where the platform defines it (Linux — production; Windows test
+        // runs fall back to the realpath identity check above alone). Only an
+        // ENOENT is a skip; any other failure is a real read problem that
+        // must surface as a 500, not ship as a silently partial archive.
+        const handle = await fs
+          .open(abs, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0))
+          .catch((err: NodeJS.ErrnoException) => {
+            if (err.code === 'ENOENT') return null; // deleted since the walk — an absence
+            if (err.code === 'ELOOP') {
+              // O_NOFOLLOW's spelling of "the final component is a symlink".
+              console.warn(`[tool-manuals] archive of "${folder}": ${rel} is a symlink — not supported in plugins, skipped.`);
+              return null;
+            }
+            throw err;
+          });
+        if (handle === null) continue;
+        try {
+          // fstat on the handle types and sizes the OPENED file — the size
+          // still gates BEFORE content, because rejecting after the read
+          // would already have spiked memory by exactly the payload the
+          // limit exists to refuse.
+          const stat = await handle.stat();
+          if (!stat.isFile()) continue;
+          bytes += stat.size;
+          if (bytes > MAX_ARCHIVE_BYTES) {
+            return void res.status(413).json({
+              error: `Plugin "${folder}" exceeds the ${MAX_ARCHIVE_BYTES / (1024 * 1024)}MB archive limit.`,
+            });
+          }
+          // Unix mode rides in the zip attrs so a `./`-command stdio server is
+          // still executable after materialization (0 on Windows — harmless).
+          // PLAIN mode, no shifting: adm-zip masks a numeric attr with 0xfff and
+          // positions it into the external-attribute high bits itself — a
+          // pre-shifted value is destroyed by that mask.
+          zip.addFile(rel, await handle.readFile(), '', stat.mode & 0o7777);
+          included += 1;
+        } finally {
+          await handle.close();
+        }
+      }
+      // An all-filtered plugin looks exactly like an absent one — a 404 must
+      // not confirm to a keyless caller that the folder exists.
+      if (included === 0) return void res.status(404).json({ error: 'Not found' });
+      res.setHeader('Content-Type', 'application/zip');
+      res.send(zip.toBuffer());
+    } catch (err) {
+      console.error('[tool-manuals] plugin archive failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to archive plugin' });
+    }
+  });
+
   router.get('/tools/:slug/manual', manualAuth, async (req, res) => {
     try {
       const email = await callerEmail(req);
@@ -89,9 +265,54 @@ export function createToolManualsAgentRoutes(
  *                            literal sibling is shadowed by the param segment;
  *                            `preview` is POST-only, so it never collides.
  */
-export function createToolManualsBrowserRoutes(toolManualService: IToolManualService): express.Router {
+export function createToolManualsBrowserRoutes(
+  toolManualService: IToolManualService,
+  serverEdit?: { service: McpServerEditService; getUser: (userId: string) => Promise<AuthUser | undefined> },
+): express.Router {
   const router = express.Router();
 
+  /**
+   * Server-scoped read/write of one MCP server — the tool page's edit form.
+   * One server's truth spans mcp.json AND plugin.json's extensions block; a
+   * raw file editor shows a writer half of it at best, so the form talks to
+   * this pair instead. PUT commits both files together and refuses the states
+   * that would strand a half (see McpServerEditService).
+   */
+  router.get('/tools/:slug/server', async (req, res) => {
+    if (!serverEdit) return void res.status(404).json({ error: 'Not available' });
+    const email = req.userEmail;
+    if (!email) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const view = await serverEdit.service.getServer(email, String(req.params.slug));
+      if (!view) return void res.status(404).json({ error: 'Not found' });
+      res.json(view);
+    } catch (err) {
+      console.error('[tool-manuals] server read failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to read the server' });
+    }
+  });
+
+  router.put('/tools/:slug/server', async (req, res) => {
+    if (!serverEdit) return void res.status(404).json({ error: 'Not available' });
+    if (!req.userId) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const user = await serverEdit.getUser(req.userId);
+      if (!user) return void res.status(401).json({ error: 'Not authenticated' });
+      const result = await serverEdit.service.putServer(
+        user,
+        String(req.params.slug),
+        (req.body ?? {}) as McpServerWrite,
+      );
+      res.json(result);
+    } catch (err) {
+      if (err instanceof McpServerEditError) {
+        return void res.status(err.status).json({ error: err.message });
+      }
+      console.error('[tool-manuals] server write failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to save the server' });
+    }
+  });
+
   router.get('/tools', async (req, res) => {
     const email = req.userEmail;
     if (!email) return void res.status(401).json({ error: 'Not authenticated' });

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -9,11 +9,18 @@ import {
   DefaultVariableSubstitutor,
   type CallTemplate,
 } from '@utcp/sdk';
-import { DEFAULT_BRANCH, GROUPS_DIR } from '@bevel-software/platform-shared';
+import {
+  DEFAULT_BRANCH,
+  PLUGINS_DIR,
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+} from '@bevel-software/platform-shared';
+import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { RESERVED_VARIABLE_NAMES, findReservedVariableRef } from '../../shared/variable-refs.js';
 import { extractFrontmatter, resolveDeclaredId, isValidId, dedupeById } from '../../shared/frontmatter-id.js';
 import { walkFiles } from '../../shared/fs-walk.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
@@ -27,6 +34,7 @@ import {
   EXTERNAL_KB_MANUAL_NAME,
   type IToolManualService,
   type ToolManualDescriptor,
+  type ToolManualDescriptorBase,
   type ToolManualSummary,
   type ToolManualDetail,
   type ToolCapability,
@@ -60,46 +68,26 @@ const MAX_CAPABILITIES = 100;
 const RESERVED_TOOL_NAMESPACES = [INTERNAL_MANUAL_NAME, EXTERNAL_KB_MANUAL_NAME].map((n) => n.toLowerCase());
 
 /**
- * Variable names the platform seeds for its own (Bevel-hosted) manuals:
- * `<ns>_API_URL` points a manual at the backend and `<ns>_CONNECTION_KEY`
- * carries the platform bearer. No user `.tool` may REFERENCE them
- * (`${API_URL}` / `$API_URL`), in any `.tool` type: the only seeded user
- * namespace is an inline `.tool`'s (its discovery template is platform-served),
- * and a reference inside author-written content would resolve platform creds
- * into a request the author shaped. Refusing every `.tool` at the producing
- * boundary makes "user tools never carry platform credentials" structural
- * rather than dependent on which namespaces happen to be seeded.
+ * No user `.tool` may REFERENCE the platform-seeded variables (`${API_URL}` /
+ * `$API_URL`), in any `.tool` type: the only seeded user namespace is an
+ * inline `.tool`'s (its discovery template is platform-served), and a
+ * reference inside author-written content would resolve platform creds into a
+ * request the author shaped. Refusing every `.tool` at the producing boundary
+ * makes "user tools never carry platform credentials" structural rather than
+ * dependent on which namespaces happen to be seeded. The names and the
+ * reference grammar live in `shared/variable-refs.ts` — one definition for
+ * every boundary that classifies references.
  */
-const RESERVED_VARIABLE_NAMES: readonly string[] = ['API_URL', 'CONNECTION_KEY'];
-
-/** The SDK substitutor's reference grammar, exactly: `${VAR}` or `$VAR`. */
-const VARIABLE_REFERENCE_RE = /\$\{([a-zA-Z0-9_]+)\}|\$([a-zA-Z0-9_]+)/g;
-
-/**
- * A REFERENCE is reserved by SUFFIX, not by exact name: the substitutor looks a
- * variable up under the manual's UTCP namespace first, so `${<ns>_CONNECTION_KEY}`
- * resolves the very same seeded value the bare `${CONNECTION_KEY}` does. Matching
- * the bare name only would let a `.tool` reach the platform bearer just by
- * spelling the namespace out. Suffix matching also refuses harmless-looking
- * near-misses (`MY_API_URL`) — deliberately fail-closed: a `.tool` author who
- * wants their own base URL has the whole namespace minus two suffixes.
- */
-function isReservedVariableRef(varName: string): boolean {
-  return RESERVED_VARIABLE_NAMES.some((reserved) => varName.endsWith(reserved));
-}
 
 /** Throw if any string in the `.tool` document references a reserved variable. */
 function assertNoReservedVariableRefs(doc: unknown, name: string): void {
-  const text = JSON.stringify(doc) ?? '';
-  for (const match of text.matchAll(VARIABLE_REFERENCE_RE)) {
-    const varName = match[1] ?? match[2];
-    if (isReservedVariableRef(varName)) {
-      throw new Error(
-        `\`.tool\` "${name}" references the reserved variable "${match[0]}" — ` +
-          'API_URL and CONNECTION_KEY (bare or namespaced, e.g. `<namespace>_CONNECTION_KEY`) ' +
-          'are seeded by the platform for its own manuals and may not appear anywhere in a `.tool`.',
-      );
-    }
+  const ref = findReservedVariableRef(doc);
+  if (ref !== null) {
+    throw new Error(
+      `\`.tool\` "${name}" references the reserved variable "${ref}" — ` +
+        'API_URL and CONNECTION_KEY (bare or namespaced, e.g. `<namespace>_CONNECTION_KEY`) ' +
+        'are seeded by the platform for its own manuals and may not appear anywhere in a `.tool`.',
+    );
   }
 }
 
@@ -270,7 +258,7 @@ export class ToolManualService implements IToolManualService {
   async preview(content: string): Promise<ToolManualPreview> {
     let descriptor: ToolManualDescriptor;
     try {
-      descriptor = normalizeToolManual('draft', 'Groups/draft.tool', content);
+      descriptor = normalizeToolManual('draft', 'Plugins/draft.tool', content);
     } catch (err) {
       return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
     }
@@ -316,6 +304,28 @@ export class ToolManualService implements IToolManualService {
         headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
       };
     }
+    if (m.type === 'mcp' && m.stdio) {
+      // A stdio server, for LOCAL consumers only (`remote: false` is implied
+      // at discovery). Command/args/env/cwd pass through verbatim — the Agent
+      // Plugins placeholders (`${PLUGIN_ROOT}`/`${PLUGIN_DATA}`) are expanded
+      // by the LOCAL runtime against its materialized plugin copy; this
+      // process has no such paths and must not guess them.
+      return {
+        name: m.name,
+        call_template_type: 'mcp',
+        config: {
+          mcpServers: {
+            [m.name]: {
+              transport: 'stdio',
+              command: m.stdio.command,
+              args: m.stdio.args,
+              ...(m.stdio.env ? { env: m.stdio.env } : {}),
+              ...(m.stdio.cwd ? { cwd: m.stdio.cwd } : {}),
+            },
+          },
+        },
+      };
+    }
     if (m.type === 'mcp') {
       // Remote (HTTP/streamable) MCP server. Exact plugin field shape is
       // finalized in Phase 4 (native `@utcp/mcp`); the proxy try/catches
@@ -487,14 +497,41 @@ export class ToolManualService implements IToolManualService {
     }
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
-    // A `.tool` sits under `Groups/`, beside the skills that use it.
+    // A `.tool` sits under `Plugins/`, beside the skills that use it.
     const files: { abs: string; rel: string }[] = [];
-    const root = path.join(kbRoot, GROUPS_DIR);
+    const root = path.join(kbRoot, PLUGINS_DIR);
     for (const rel of await walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))) {
-      files.push({ abs: path.join(root, rel), rel: `${GROUPS_DIR}/${rel}` });
+      files.push({ abs: path.join(root, rel), rel: `${PLUGINS_DIR}/${rel}` });
     }
 
+    // MCP servers come from each plugin's mcp.json — the AUTHORITATIVE source
+    // (the Agent Plugins fixed location), synthesized into the same descriptor
+    // shape. Listed BEFORE the `.tool` files: on a name collision (a legacy
+    // mcp `.tool` the migration has not converted yet), the shared dedup keeps
+    // the first occurrence, and the authoritative source must be the one kept.
     const parsed: ToolManualDescriptor[] = [];
+    let pluginFolders: string[] = [];
+    try {
+      pluginFolders = (await fs.readdir(root, { withFileTypes: true }))
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      /* no Plugins/ root — nothing to scan */
+    }
+    for (const folder of pluginFolders) {
+      let mcpJson: string;
+      try {
+        mcpJson = await fs.readFile(path.join(root, folder, PLUGIN_MCP_FILE), 'utf-8');
+      } catch {
+        continue; // no mcp.json is the common case, not an error
+      }
+      const pluginJson = await fs
+        .readFile(path.join(root, folder, PLUGIN_MANIFEST_FILE), 'utf-8')
+        .catch(() => null);
+      parsed.push(...descriptorsFromMcpJson(folder, mcpJson, pluginJson));
+    }
+
     for (const f of files) {
       let content: string;
       try {
@@ -654,7 +691,10 @@ export function normalizeToolManual(
   // reference the platform-seeded variables.
   assertNoReservedVariableRefs(obj, name);
 
-  const descriptor: ToolManualDescriptor = {
+  // The non-stdio constituent of the union, by name: `.tool` parsing can
+  // never produce a spawn spec, and the stdio side pins `remote: false`,
+  // which this builder must stay free to set from the file's own `remote:`.
+  const descriptor: ToolManualDescriptorBase & { remote?: boolean; stdio?: undefined } = {
     slug: provisionalSlug,
     name,
     path: repoPath,

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -179,9 +179,12 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
     description:
       'List tools your workspace admins configured that run ONLY in a local environment ' +
       '(e.g. a self-hosted MCP server on localhost) and therefore cannot be called through this ' +
-      'remote endpoint. Each entry gives the tool’s name and its `.tool` file path in the knowledge ' +
-      'base — read that file with `read_file` and configure the tool yourself in your local setup ' +
-      '(e.g. add the MCP server to your client). ' +
+      'remote endpoint. To CALL them, run the workspace as a local MCP server instead of this one: ' +
+      '`npx @bevel-software/hexis-mcp --url <workspace-url> --key <connection-key>` serves every tool ' +
+      'you have here plus these, because it runs where they exist (their own credentials come from ' +
+      'that process\'s environment). Otherwise each entry gives the tool’s name and its `.tool` file ' +
+      'path in the knowledge base — read that file with `read_file` and wire the tool into your local ' +
+      'setup by hand. ' +
       (await localToolsLine(svc, userEmail)),
     path: '/api/agent/tools/list_local_tools',
     inputs: { type: 'object', properties: {}, additionalProperties: false },

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -93,7 +93,7 @@ function makeAccessControl(): IAccessControl {
     grantSources: vi.fn().mockResolvedValue({}),
     invalidate: vi.fn(),
     findEmailByHash: vi.fn().mockResolvedValue(null),
-    kbPrincipals: vi.fn().mockResolvedValue({ groups: [], people: [] }),
+    kbPrincipals: vi.fn().mockResolvedValue({ plugins: [], people: [] }),
     validateRolesYaml: vi.fn().mockReturnValue({ ok: true }),
     referencesToRole: vi.fn().mockResolvedValue([]),
     canWriteAtRef: vi.fn().mockResolvedValue(null),

package/src/modules/workflow/git/__tests__/branch-name.test.ts

@@ -49,9 +49,9 @@ describe('assertValidRelativePath', () => {
     // now sets `GIT_LITERAL_PATHSPECS=1` on every git subprocess, so KB files
     // arriving with bracketed prefixes (`[Approved]`, `[New]`, `[Updated …]`)
     // or other glob metacharacters round-trip through commit cleanly.
-    '[Approved] Purchasing_Order archive.docx',
-    'Purchasing/[New] Purchasing_E-Invoicing DE.docx',
-    'Purchasing/[Updated 03.09.2025] Purchasing_How to search_Product detail page.docx',
+    '[Approved] Handbook_Order archive.docx',
+    'Handbook/[New] Handbook_E-Invoicing DE.docx',
+    'Handbook/[Updated 03.09.2025] Handbook_How to search_Detail page.docx',
     'docs/wildcard*name.md',
     'docs/question?name.md',
     'docs/bang!name.md',

package/src/modules/workflow/git/__tests__/git.service.accessGating.test.ts

@@ -124,7 +124,7 @@ function recordingAccessControl(opts: {
     eligibleWritersForPathsAtRef: async (_w, _ref, paths) =>
       new Map(paths.map((p) => [p, { roles: [], users: [], emails: new Set<string>() }])),
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };
@@ -279,8 +279,8 @@ describe('GitService — push gate uses origin/<branch> (not HEAD or working tre
   });
 
   it('systemAuthorized skips the gate entirely, and the push still lands', async () => {
-    // The group-provisioning path: its endpoint IS the authorization (any
-    // signed-in user may claim an unused name under Groups/), and the gate
+    // The plugin-provisioning path: its endpoint IS the authorization (any
+    // signed-in user may claim an unused name under Plugins/), and the gate
     // could only read the new folder's chain at origin as `write: Admin`.
     const { svc, calls } = await setupWithOrigin();
     await svc.push(workspaceId, USER, { systemAuthorized: true });

package/src/modules/workflow/git/__tests__/git.service.commitFile.test.ts

@@ -139,8 +139,10 @@ describe('GitService.commitFile — skipValidator', () => {
       'knowledge-base',
     );
 
-    const relPath = 'Purchasing/[Updated 03.09.2025] Purchasing_How to search_Product detail page.md';
-    await fs.mkdir(path.join(repo, 'Purchasing'), { recursive: true });
+    // Shape mirrors the reported filename (bracketed status prefix carrying a
+    // date, underscores, spaces) without reproducing anyone's actual content.
+    const relPath = 'Handbook/[Updated 03.09.2025] Handbook_How to search_Detail page.md';
+    await fs.mkdir(path.join(repo, 'Handbook'), { recursive: true });
     await fs.writeFile(path.join(repo, relPath), 'content\n');
 
     const change = await svc.commitFile(workspaceId, USER, relPath);
@@ -168,15 +170,18 @@ describe('GitService.commitFile — skipValidator', () => {
       'knowledge-base',
     );
 
+    // Synthetic segments matching the SHAPE of real deep-KB naming (numbered
+    // prefixes, parenthesised abbreviations, kebab tails) — the property under
+    // test is only the total length, asserted below.
     const deepDir = path.join(
-      'Product',
+      'Handbook',
       'Knowledge',
-      '1. Service Commitment Management',
-      '1.1 In - Architecture Layering (AL)',
-      '0-Governance',
-      '0.5-Layer-Group-Specific-Governance-Principles',
+      '1. First-Level Section With A Long Name',
+      '1.1 In - Second-Level Subsection (SL)',
+      '0-Reference',
+      '0.5-Third-Level-Reference-Naming-Convention',
     );
-    const fileName = '0.5.5-Buyer-Side-Commercial-Agreement-Governance.md';
+    const fileName = '0.5.5-A-Deeply-Nested-Reference-Document-With-A-Long-Name.md';
     const relPath = path.posix.join(deepDir.split(path.sep).join('/'), fileName);
     expect(`Update ${relPath}`.length).toBeGreaterThan(200);
 

package/src/modules/workflow/git/__tests__/git.service.deleteBranch.test.ts

@@ -134,7 +134,7 @@ function fakeAccessControl(adminEmails: string[]): IAccessControl {
     canOwner: async () => notImpl(),
     invalidate: () => {},
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
     canWriteAtRef: async () => null,

package/src/modules/workflow/git/__tests__/pull-request.service.test.ts

@@ -64,7 +64,7 @@ function makeAccessControl(byRef: WritersByRefAndPath): IAccessControl {
     eligibleWritersAtRef: async () => null,
     eligibleWritersForPathsAtRef: async () => null,
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };

package/src/modules/workflow/git/git.service.ts

@@ -1047,12 +1047,12 @@ export class GitService implements IGitService {
       // protected pushes; that's defence-in-depth against local rebases or
       // `commit-tree` shenanigans that might bypass the commit-time gate.
       // `systemAuthorized` skips the gate for flows whose ENDPOINT is the
-      // authorization — group provisioning commits an access.md into a
+      // authorization — plugin provisioning commits an access.md into a
       // folder that does not exist at origin yet, which this gate can only
       // ever read as "write: Admin". The provisioning service has already
       // decided the write is legitimate (unused name, exclusive create);
       // gating it here again just refuses every non-admin the product
-      // promised a group to.
+      // promised a plugin to.
       if (isProtectedBranch(branch) && !opts?.systemAuthorized) {
         const touched = await this.unpushedTouchedPaths(cwd);
         await this.assertCanWriteAtRef(

package/src/modules/workflow/review-workflow/__tests__/approval-states.test.ts

@@ -164,7 +164,7 @@ function makeAccessControl(byPath: EligibilityByPath): IAccessControl {
       return result;
     },
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };

package/src/modules/workflow/review-workflow/__tests__/cancel-pr.test.ts

@@ -53,7 +53,7 @@ function makeAccessControl(adminEmails: string[] = []): IAccessControl {
     eligibleWritersAtRef: async () => null,
     eligibleWritersForPathsAtRef: async () => null,
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };