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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.7.5",
+  "version": "0.9.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "@utcp/http": "^1.1.7",
     "@utcp/mcp": "^1.1.3",
     "@utcp/sdk": "^1.1.1",
-    "adm-zip": "^0.5.17",
+    "adm-zip": "^0.6.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.0",
     "drizzle-orm": "^0.45.2",
@@ -46,7 +46,8 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-shared": "0.7.5"
+    "@bevel-software/platform-mcp-core": "0.9.0",
+    "@bevel-software/platform-shared": "0.9.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -60,7 +61,7 @@
     "drizzle-kit": "^0.31.10",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0",
-    "vitest": "^2.1.9"
+    "vitest": "^3.2.6"
   },
   "license": "Apache-2.0",
   "repository": {

package/src/assets.ts

@@ -1,25 +1,25 @@
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/**
- * Locations of the assets shipped INSIDE this package (`files` in
- * package.json): the squashed core migration history (`migrations/`) and the
- * KB seed template (`kb-template/`). Both live at the PACKAGE ROOT, and this
- * module is a direct child of either `src/` (in-repo / tsx) or `dist/`
- * (compiled) — so one `..` hop from the module URL reaches the package root
- * in BOTH layouts. Resolved lazily so bundlers that rewrite `import.meta.url`
- * still get a sensible answer at call time.
- */
-function packageRoot(): string {
-  return fileURLToPath(new URL('..', import.meta.url));
-}
-
-/** Absolute path of the packaged core Drizzle migrations folder. */
-export function coreMigrationsDir(): string {
-  return path.join(packageRoot(), 'migrations');
-}
-
-/** Absolute path of the packaged KB seed template (`kb-template/`). */
-export function defaultKbTemplateDir(): string {
-  return path.join(packageRoot(), 'kb-template');
-}
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Locations of the assets shipped INSIDE this package (`files` in
+ * package.json): the squashed core migration history (`migrations/`) and the
+ * KB seed template (`kb-template/`). Both live at the PACKAGE ROOT, and this
+ * module is a direct child of either `src/` (in-repo / tsx) or `dist/`
+ * (compiled) — so one `..` hop from the module URL reaches the package root
+ * in BOTH layouts. Resolved lazily so bundlers that rewrite `import.meta.url`
+ * still get a sensible answer at call time.
+ */
+function packageRoot(): string {
+  return fileURLToPath(new URL('..', import.meta.url));
+}
+
+/** Absolute path of the packaged core Drizzle migrations folder. */
+export function coreMigrationsDir(): string {
+  return path.join(packageRoot(), 'migrations');
+}
+
+/** Absolute path of the packaged KB seed template (`kb-template/`). */
+export function defaultKbTemplateDir(): string {
+  return path.join(packageRoot(), 'kb-template');
+}

package/src/core/core-ports.ts

@@ -1,106 +1,113 @@
-import type { ISessionSink } from '../modules/workspace/session-sink.js';
-import type {
-  ISystemNoticeSink,
-  RecoveryAgentRunner,
-} from '../modules/workflow/pending-commits.worker.js';
-import type { ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
-import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
-import type { IErasureParticipant } from '../modules/auth/account-erasure.service.js';
-
-/**
- * Every seam the enterprise overlay can fill in the CORE composition
- * (`createCoreServices`). All fields are optional; each has a safe core-only
- * default, so `createCoreServices(config)` with no ports yields a fully
- * working core deployment.
- *
- * Two consumption patterns exist, and they matter for wiring order:
- *
- * - CONSTRUCTION-TIME ports (`recoveryAgent`, `systemNotice`,
- *   `erasureParticipants`): dereferenced while core services are being
- *   constructed. Enterprise implementations of these need core services that
- *   don't exist yet at that point (the background-agent factory, the thread
- *   service, …), so the enterprise root passes FORWARDING DELEGATORS / a
- *   mutable array here and assigns the real targets right after
- *   `createCoreServices` returns. That is safe because core only *calls* these
- *   ports at request/commit/erasure time, long after boot — the same
- *   late-binding pattern the composition root already uses for e.g. the MCP
- *   OAuth revoke closure.
- *
- * - SERVER-TIME seams (`sessionSink`, `usageMeter`, `authProviders`): only
- *   read when `createCoreServer` mounts routes / registers tools. Core seeds
- *   them onto `CoreServices` from these ports (with the defaults below); the
- *   enterprise root overwrites the `CoreServices` fields (or pushes into the
- *   `authProviders` array) after construction, before the server is built.
- *
- * (Commit-time KB validation and the ontology write block are NOT ports:
- * they are workflow lifecycle HOOKS the enterprise root registers on
- * `workflowService.hooks` after construction — see
- * `modules/workflow/workflow-hooks.ts`.)
- */
-export interface CorePorts {
-  /**
-   * Backs the `start_session` tool. Core default: {@link UuidSessionSink}
-   * (a bare random id). Enterprise substitutes a sink that mints a real chat
-   * thread so the same id works end to end with `ask`.
-   */
-  sessionSink?: ISessionSink;
-  /**
-   * Recovery-agent dispatcher for the pending-commits worker. The worker
-   * requires one, so the core default is {@link noopRecoveryAgent} — a run
-   * that just returns, meaning the row stays pending until the recovery
-   * budget is exhausted and the worker escalates via `systemNotice`.
-   */
-  recoveryAgent?: RecoveryAgentRunner;
-  /**
-   * Where the pending-commits worker escalates terminal failures. Core
-   * default: {@link consoleSystemNoticeSink} (stderr, no dashboard).
-   * Enterprise passes its feedback service.
-   */
-  systemNotice?: ISystemNoticeSink;
-  /**
-   * Per-connection-key LLM usage metering shown on the connection-key
-   * management routes. Core default: {@link unmeteredLlmUsage} (no proxy,
-   * nothing to meter). Enterprise passes the LLM proxy's usage service.
-   */
-  usageMeter?: ILlmUsageMeter;
-  /**
-   * SSO login plugins the auth router mounts. Core default: `[]` (password
-   * login only). The array instance is kept on `CoreServices.authProviders`,
-   * so an enterprise root may pass an array it fills after construction.
-   */
-  authProviders?: AuthProviderPlugin[];
-  /**
-   * Module-owned GDPR-erasure slices run by `AccountErasureService`. Core
-   * default: `[]` (core erases only the rows it owns). The array reference is
-   * held — not copied — so an enterprise root may pass an array it fills after
-   * construction (participants are only iterated at erasure time).
-   */
-  erasureParticipants?: IErasureParticipant[];
-  /**
-   * Root folders THIS distribution reserves in the knowledge base, on top of
-   * core's `KnowledgeBase/` + `Groups/`. Core default: `[]`.
-   *
-   * A name here does two things: the seeder guarantees the folder exists on
-   * every branch it tops up, and — because the names are already reserved in
-   * `kb-layout.ts` — the file tree keeps rendering it as its own root instead
-   * of folding it into Knowledge as stray content.
-   *
-   * The folder is created as an empty `<dir>/.gitkeep`, written rather than
-   * copied, so reserving a root does not oblige a distribution to fork the
-   * packaged template. Ship a `KB_TEMPLATE_DIR` of your own when those folders
-   * should arrive carrying READMEs.
-   */
-  kbExtraRootDirs?: readonly string[];
-}
-
-/**
- * Core default recovery agent: does nothing. The worker's retry ladder still
- * works — a stuck row burns its recovery budget on these no-op runs and then
- * escalates to the `systemNotice` sink, which is exactly the "no recovery
- * agent available" behavior a core-only deployment wants.
- */
-export const noopRecoveryAgent: RecoveryAgentRunner = {
-  async run(): Promise<void> {
-    // Intentionally empty — see doc comment.
-  },
-};
+import type { ISessionSink } from '../modules/workspace/session-sink.js';
+import type {
+  ISystemNoticeSink,
+  RecoveryAgentRunner,
+} from '../modules/workflow/pending-commits.worker.js';
+import type { ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
+import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
+import type { IErasureParticipant } from '../modules/auth/account-erasure.service.js';
+import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
+
+/**
+ * Every seam the enterprise overlay can fill in the CORE composition
+ * (`createCoreServices`). All fields are optional; each has a safe core-only
+ * default, so `createCoreServices(config)` with no ports yields a fully
+ * working core deployment.
+ *
+ * Two consumption patterns exist, and they matter for wiring order:
+ *
+ * - CONSTRUCTION-TIME ports (`recoveryAgent`, `systemNotice`,
+ *   `erasureParticipants`): dereferenced while core services are being
+ *   constructed. Enterprise implementations of these need core services that
+ *   don't exist yet at that point (the background-agent factory, the thread
+ *   service, …), so the enterprise root passes FORWARDING DELEGATORS / a
+ *   mutable array here and assigns the real targets right after
+ *   `createCoreServices` returns. That is safe because core only *calls* these
+ *   ports at request/commit/erasure time, long after boot — the same
+ *   late-binding pattern the composition root already uses for e.g. the MCP
+ *   OAuth revoke closure.
+ *
+ * - SERVER-TIME seams (`sessionSink`, `usageMeter`, `authProviders`): only
+ *   read when `createCoreServer` mounts routes / registers tools. Core seeds
+ *   them onto `CoreServices` from these ports (with the defaults below); the
+ *   enterprise root overwrites the `CoreServices` fields (or pushes into the
+ *   `authProviders` array) after construction, before the server is built.
+ *
+ * (Commit-time KB validation and the ontology write block are NOT ports:
+ * they are workflow lifecycle HOOKS the enterprise root registers on
+ * `workflowService.hooks` after construction — see
+ * `modules/workflow/workflow-hooks.ts`.)
+ */
+export interface CorePorts {
+  /**
+   * Backs the `start_session` tool. Core default: {@link UuidSessionSink}
+   * (a bare random id). Enterprise substitutes a sink that mints a real chat
+   * thread so the same id works end to end with `ask`.
+   */
+  sessionSink?: ISessionSink;
+  /**
+   * Recovery-agent dispatcher for the pending-commits worker. The worker
+   * requires one, so the core default is {@link noopRecoveryAgent} — a run
+   * that just returns, meaning the row stays pending until the recovery
+   * budget is exhausted and the worker escalates via `systemNotice`.
+   */
+  recoveryAgent?: RecoveryAgentRunner;
+  /**
+   * Where the pending-commits worker escalates terminal failures. Core
+   * default: {@link consoleSystemNoticeSink} (stderr, no dashboard).
+   * Enterprise passes its feedback service.
+   */
+  systemNotice?: ISystemNoticeSink;
+  /**
+   * Per-connection-key LLM usage metering shown on the connection-key
+   * management routes. Core default: {@link unmeteredLlmUsage} (no proxy,
+   * nothing to meter). Enterprise passes the LLM proxy's usage service.
+   */
+  usageMeter?: ILlmUsageMeter;
+  /**
+   * SSO login plugins the auth router mounts. Core default: `[]` (password
+   * login only). The array instance is kept on `CoreServices.authProviders`,
+   * so an enterprise root may pass an array it fills after construction.
+   */
+  authProviders?: AuthProviderPlugin[];
+  /**
+   * Module-owned GDPR-erasure slices run by `AccountErasureService`. Core
+   * default: `[]` (core erases only the rows it owns). The array reference is
+   * held — not copied — so an enterprise root may pass an array it fills after
+   * construction (participants are only iterated at erasure time).
+   */
+  erasureParticipants?: IErasureParticipant[];
+  /**
+   * Root folders THIS distribution reserves in the knowledge base, on top of
+   * core's `KnowledgeBase/` + `Plugins/`. Core default: `[]`.
+   *
+   * A name here does two things: the seeder guarantees the folder exists on
+   * every branch it tops up, and — because the names are already reserved in
+   * `kb-layout.ts` — the file tree keeps rendering it as its own root instead
+   * of folding it into Knowledge as stray content.
+   *
+   * The folder is created as an empty `<dir>/.gitkeep`, written rather than
+   * copied, so reserving a root does not oblige a distribution to fork the
+   * packaged template. Ship a `KB_TEMPLATE_DIR` of your own when those folders
+   * should arrive carrying READMEs.
+   */
+  kbExtraRootDirs?: readonly string[];
+  /**
+   * Steps THIS distribution appends to the KB startup phase, run after core's
+   * own steps in array order (see `startup/on-server-start.ts` for the
+   * contract each step signs up to). Core default: `[]`.
+   */
+  kbStartupSteps?: readonly OnServerStart[];
+}
+
+/**
+ * Core default recovery agent: does nothing. The worker's retry ladder still
+ * works — a stuck row burns its recovery budget on these no-op runs and then
+ * escalates to the `systemNotice` sink, which is exactly the "no recovery
+ * agent available" behavior a core-only deployment wants.
+ */
+export const noopRecoveryAgent: RecoveryAgentRunner = {
+  async run(): Promise<void> {
+    // Intentionally empty — see doc comment.
+  },
+};

package/src/core/create-core-server.ts

@@ -21,7 +21,7 @@ import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.
 import { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
 import { RECOVERY_BOT_EMAIL } from '../modules/workflow/recovery-bot.js';
 import { registerSkillsTools, createSkillsRoutes } from '../modules/skills/index.js';
-import { createGroupsRoutes } from '../modules/groups/index.js';
+import { createPluginsRoutes } from '../modules/plugins/index.js';
 import type { SessionOntologyGate } from '../modules/workspace/session-ontology.gate.js';
 import {
   createSecretsVaultRoutes,
@@ -30,7 +30,7 @@ import {
 import { createAdminAccessRoutes } from '../modules/admin/admin-access.routes.js';
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createSetupRoutes } from '../modules/settings/setup.routes.js';
-import { DEFAULT_BRANCH, PROTECTED_BRANCHES } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PROTECTED_BRANCHES, type AuthUser } from '@bevel-software/platform-shared';
 import { GIT_SHA } from '../version.js';
 import type { CoreServices } from './create-core-services.js';
 
@@ -150,6 +150,30 @@ export async function createCoreServer(
     res.json({ status: 'ok', sha: GIT_SHA, timestamp: Date.now() });
   });
 
+  /**
+   * This deployment's MCP endpoint, derived ONCE.
+   *
+   * Two consumers must agree on it: `/api/config` below, which is where the
+   * frontend learns what address to show people, and the OAuth
+   * `resourceServerUrl` further down, which is the resource identifier the
+   * protected-resource metadata publishes and therefore the one that decides
+   * whether a connection actually works.
+   *
+   * A constant rather than the same expression written twice. The frontend
+   * carried the two-places version of this bug for a long time — six inline
+   * sites each rebuilding the address, held together by a docstring asserting
+   * they could not diverge — and a comment is not a mechanism.
+   *
+   * Userinfo is STRIPPED: a `PUBLIC_BACKEND_URL` spelled with `user:pass@`
+   * (a basic-auth proxy in front of the deployment, say) would otherwise be
+   * republished verbatim by the unauthenticated `/api/config` below — a
+   * credential handed to any caller. The address is ours to publish; the
+   * credential never was.
+   */
+  const mcpResourceUrl = new URL('/api/mcp', core.config.publicBackendUrl);
+  mcpResourceUrl.username = '';
+  mcpResourceUrl.password = '';
+
   /**
    * The handful of facts the browser needs BEFORE it can render anything, and
    * therefore before it can authenticate: the branch model.
@@ -170,15 +194,46 @@ export async function createCoreServer(
         defaultBranch: DEFAULT_BRANCH,
         protectedBranches: [...PROTECTED_BRANCHES],
       },
+      /**
+       * The same value the OAuth metadata publishes (see `mcpResourceUrl`).
+       *
+       * The frontend used to build this from `window.location.origin`, which
+       * is the browser's idea of our address rather than ours. The two agree
+       * on a simple deployment and disagree behind a proxy, on a second
+       * domain, or on an internal hostname — and the one that decides whether
+       * a connection works is this one.
+       *
+       * That was survivable while every surface was copy-paste: a human sees
+       * the host before pasting it. It stops being survivable the moment we
+       * hand the URL to a third party (a connector install link), where
+       * nobody reads it and the failure surfaces inside someone else's UI.
+       */
+      mcpUrl: mcpResourceUrl.toString(),
     });
   });
 
-  // Close change requests whose source branch has been deleted. Not awaited:
-  // it fetches from origin, and a slow or unreachable remote must not hold up
-  // the server — nothing downstream depends on the result, and the requests it
-  // closes have been unusable since the branch went away, so landing a few
-  // seconds into uptime is soon enough. Errors are swallowed inside the sweep,
-  // which fails safe by closing nothing.
+  // Overlay boot-time side effects (startup reconciles, periodic sweeps).
+  await ext.onBoot?.(core);
+
+  // The KB startup phase — AFTER the distribution's onBoot, because a FATAL
+  // template finding raised there must stop the boot before anything seeds
+  // from that template; the runner then brings every branch up to this build
+  // before any route can serve KB content. Throws to stop the boot (the
+  // container's restart policy is the retry) — see kb-startup-runner.ts.
+  await core.kbStartupRunner.runAll();
+
+  // Close change requests whose source branch has been deleted. SEQUENCED
+  // AFTER the startup phase above, for two reasons: the sweep's fresh fetch
+  // lazily bootstraps and fetches the same default-branch clone the runner
+  // maintains (kicking it off earlier races the runner's clone/fetch of that
+  // very directory), and on a brand-new deployment it would run before the
+  // empty remote is seeded, fail its clone, swallow the error, and leave
+  // deleted-branch CRs open for the whole process. Still not awaited from
+  // here on: a slow or unreachable remote must not hold up the server —
+  // nothing downstream depends on the result, and the requests it closes
+  // have been unusable since the branch went away, so landing a few seconds
+  // into uptime is soon enough. Errors are swallowed inside the sweep, which
+  // fails safe by closing nothing.
   void core.workflowService
     .closeChangeRequestsWithDeletedBranches()
     .then((n) => {
@@ -188,9 +243,6 @@ export async function createCoreServer(
     })
     .catch((err) => console.warn('[cr] deleted-branch sweep failed:', err));
 
-  // Overlay boot-time side effects (startup reconciles, periodic sweeps).
-  await ext.onBoot?.(core);
-
   // Auth routes (unprotected — login endpoint must be accessible)
   app.use(
     '/api',
@@ -225,7 +277,7 @@ export async function createCoreServer(
   app.use(mcpAuthRouter({
     provider: core.mcpOAuthProvider,
     issuerUrl: new URL(core.config.publicBackendUrl),
-    resourceServerUrl: new URL('/api/mcp', core.config.publicBackendUrl),
+    resourceServerUrl: mcpResourceUrl,
     scopesSupported: ['mcp'],
     resourceName: 'Bevel MCP',
   }));
@@ -300,6 +352,7 @@ export async function createCoreServer(
     core.toolManualService,
     core.manualAuthMiddleware,
     async (userId) => (await core.authService.getUserById(userId))?.email,
+    { workspaceService: core.workspaceService, accessControl: core.accessControl, kbDirName: core.kbDirName },
   ));
   app.use('/api', toolsRouter);
 
@@ -349,23 +402,24 @@ export async function createCoreServer(
     core.eventBus,
     core.db,
     core.kbDirName,
+    [core.config.adminEmail],
   ));
   app.use(
     '/api',
     core.authMiddleware,
     createSkillsRoutes(core.skillService, core.pendingSkillsService),
   );
-  // Group enumeration + join requests. Browser-only (JWT), and fail-closed
-  // like every other read surface: groups the caller cannot access (member,
+  // Plugin enumeration + join requests. Browser-only (JWT), and fail-closed
+  // like every other read surface: plugins the caller cannot access (member,
   // manager, or discoverable via the access.md file's own read grant) are
   // absent from the list. A join request is a plain change request.
-  app.use('/api', core.authMiddleware, createGroupsRoutes(
-    core.groupIndexService,
+  app.use('/api', core.authMiddleware, createPluginsRoutes(
+    core.pluginIndexService,
     core.accessControl,
     core.workflowService,
     core.workspaceService,
     core.joinRequestsService,
-    core.groupProvisionService,
+    core.pluginProvisionService,
     core.kbDirName,
     async (req) => (req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null),
   ));
@@ -381,9 +435,20 @@ export async function createCoreServer(
   ));
   // First-run setup. Mounted with the other authed routes but touching NO
   // workspace — it has to work on a deployment that has no knowledge base yet,
-  // which is the whole reason it exists.
-  app.use('/api', core.authMiddleware, createSetupRoutes(core.settings, core.adminAccess));
-  app.use('/api', core.authMiddleware, createToolManualsBrowserRoutes(core.toolManualService));
+  // which is the whole reason it exists. The startup runner rides along for
+  // the phase's SECOND quiet moment: the save that completes setup.
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createSetupRoutes(core.settings, core.adminAccess, core.kbStartupRunner),
+  );
+  app.use('/api', core.authMiddleware, createToolManualsBrowserRoutes(core.toolManualService, {
+    service: core.mcpServerEditService,
+    getUser: async (userId) => {
+      const u = await core.authService.getUserById(userId);
+      return u ? ({ id: u.id, email: u.email, name: u.name } as AuthUser) : undefined;
+    },
+  }));
   app.use('/api', core.authMiddleware, createSecretsVaultRoutes(secretsVaultRoutesDeps));
   // The authed tail of the MCP OAuth flow: /connect calls these to describe
   // the pending authorization and, on Finish, to mint the one-time code. The