@bevel-software/platform-core-backend 0.14.0 → 0.15.1

package/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1787191920033,
       "tag": "0004_file_lock_mode",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1788791352625,
+      "tag": "0005_github_facade",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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",
@@ -32,11 +32,11 @@
     "@kenjiuno/msgreader": "^1.28.0",
     "@mastra/core": "1.35.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@utcp/cli": "^1.1.1",
+    "@utcp/cli": "^1.1.3",
     "@utcp/code-mode": "^1.2.13",
     "@utcp/direct-call": "^1.1.1",
-    "@utcp/http": "^1.1.7",
-    "@utcp/mcp": "^1.1.6",
+    "@utcp/http": "^1.1.12",
+    "@utcp/mcp": "^1.1.7",
     "@utcp/sdk": "^1.1.1",
     "adm-zip": "^0.6.0",
     "cors": "^2.8.5",
@@ -52,8 +52,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.14.0",
-    "@bevel-software/platform-shared": "0.14.0"
+    "@bevel-software/platform-mcp-core": "0.15.1",
+    "@bevel-software/platform-shared": "0.15.1"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/kb-layout-config.test.ts

@@ -0,0 +1,110 @@
+import { describe, test, expect, afterEach } from 'vitest';
+import {
+  DEFAULT_KB_LAYOUT,
+  KNOWLEDGE_BASE_DIR,
+  PLUGINS_DIR,
+  SKILLS_DIR,
+  configureKbLayout,
+  currentKbLayout,
+  ontologyRoots,
+  pluginOfPath,
+  renderKbLayoutPlaceholders,
+  reservedRootDirNames,
+  validateKbLayout,
+  validateKbRootName,
+  normalizeSkillRoot,
+} from '@bevel-software/platform-shared';
+
+/**
+ * The KB layout is module state shared by every test in the process, so each
+ * test that reconfigures it puts the defaults back — exactly what a deployment
+ * that names nothing runs with.
+ */
+afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
+
+describe('KB layout — validation', () => {
+  test('accepts the defaults and any three distinct plain folder names', () => {
+    expect(validateKbLayout({ ...DEFAULT_KB_LAYOUT })).toBeNull();
+    expect(
+      validateKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' }),
+    ).toBeNull();
+  });
+
+  test('refuses a root that could escape the repository or hide from the scanners', () => {
+    expect(validateKbRootName('')).not.toBeNull();
+    expect(validateKbRootName('a/b')).not.toBeNull();
+    expect(validateKbRootName('a\\b')).not.toBeNull();
+    expect(validateKbRootName('..')).not.toBeNull();
+    expect(validateKbRootName('.git')).not.toBeNull();
+    expect(validateKbRootName('.hidden')).not.toBeNull();
+    expect(validateKbRootName('bad\nname')).not.toBeNull();
+    // The same rule every file and folder name passes: reserved Windows
+    // names, forbidden characters, trailing dots and spaces.
+    expect(validateKbRootName('CON')).not.toBeNull();
+    expect(validateKbRootName('a\u007fb')).not.toBeNull();
+    expect(validateKbRootName('a:b')).not.toBeNull();
+    expect(validateKbRootName('name.')).not.toBeNull();
+    expect(validateKbRootName('x'.repeat(300))).not.toBeNull();
+    expect(validateKbRootName('Skills')).toBeNull();
+    expect(validateKbRootName('My Skills')).toBeNull();
+  });
+
+  test('a skill root forgives trailing slashes only — an empty segment inside is malformed', () => {
+    expect(normalizeSkillRoot('Skills/Eng/deploy/')).toBe('Skills/Eng/deploy');
+    expect(normalizeSkillRoot('Skills/Eng/deploy//')).toBe('Skills/Eng/deploy');
+    expect(normalizeSkillRoot('Skills//deploy')).toBeNull();
+    expect(normalizeSkillRoot('Skills/./deploy')).toBeNull();
+    expect(normalizeSkillRoot('/Skills/deploy')).toBeNull();
+  });
+
+  test('refuses a configurable root that takes a fixed reserved name', () => {
+    expect(
+      validateKbLayout({ knowledgeBaseDir: 'KnowledgeBase', skillsDir: 'data', pluginsDir: 'Plugins' }),
+    ).toMatch(/reserved folder name/);
+  });
+
+  test('renders placeholders without interpreting $-patterns in a folder name', () => {
+    expect(
+      renderKbLayoutPlaceholders('a {{skillsDir}} b', { knowledgeBaseDir: 'K', skillsDir: 'Sales$&', pluginsDir: 'P' }),
+    ).toBe('a Sales$& b');
+    expect(renderKbLayoutPlaceholders('no placeholders', DEFAULT_KB_LAYOUT)).toBe('no placeholders');
+  });
+
+  test('refuses two roots sharing a name, case-insensitively — one folder on a case-insensitive disk', () => {
+    expect(
+      validateKbLayout({ knowledgeBaseDir: 'KnowledgeBase', skillsDir: 'skills', pluginsDir: 'Skills' }),
+    ).toMatch(/three different names/);
+  });
+});
+
+describe('KB layout — configuration', () => {
+  test('applies the names to the live bindings every consumer reads', () => {
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    expect(KNOWLEDGE_BASE_DIR).toBe('docs');
+    expect(SKILLS_DIR).toBe('skills');
+    expect(PLUGINS_DIR).toBe('plugins');
+    expect(currentKbLayout()).toEqual({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+  });
+
+  test('the derived sets follow the configured names rather than snapshotting the defaults', () => {
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    expect(ontologyRoots()).toEqual(['docs', 'Data']);
+    expect(reservedRootDirNames().has('plugins')).toBe(true);
+    expect(reservedRootDirNames().has('Plugins')).toBe(false);
+    // Path rules read the live name too.
+    expect(pluginOfPath('plugins/GTM/skills/x/SKILL.md')).toBe('GTM');
+    expect(pluginOfPath('Plugins/GTM/skills/x/SKILL.md')).toBeNull();
+  });
+
+  test('throws on an invalid layout and leaves the current one untouched', () => {
+    expect(() =>
+      configureKbLayout({ knowledgeBaseDir: 'a', skillsDir: 'a', pluginsDir: 'b' }),
+    ).toThrow(/three different names/);
+    expect(currentKbLayout()).toEqual(DEFAULT_KB_LAYOUT);
+  });
+
+  test('trims what it applies', () => {
+    configureKbLayout({ knowledgeBaseDir: ' docs ', skillsDir: 'skills', pluginsDir: 'plugins' });
+    expect(KNOWLEDGE_BASE_DIR).toBe('docs');
+  });
+});

package/src/core/__tests__/catalog-cache-invalidation.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { FileChangeNotifier } from '../../modules/kb-fs/file-change-notifier.js';
+import { WorkflowEventBus } from '../../modules/workflow/event-bus.js';
+import { registerCatalogCacheInvalidation } from '../catalog-cache-invalidation.js';
+
+const KB_DIR = 'knowledge-base';
+
+const USER = {
+  id: 'u1',
+  email: 'someone@example.com',
+  name: 'Someone',
+} as unknown as Parameters<Parameters<FileChangeNotifier['onFilesChanged']>[0]>[0]['byUser'];
+
+function setup() {
+  const eventBus = new WorkflowEventBus();
+  const fileChangeNotifier = new FileChangeNotifier();
+  const catalogs = [
+    { invalidate: vi.fn() },
+    { invalidate: vi.fn() },
+    { invalidate: vi.fn() },
+  ];
+  const off = registerCatalogCacheInvalidation({
+    eventBus,
+    fileChangeNotifier,
+    kbDirName: KB_DIR,
+    catalogs,
+  });
+  /** How many times EVERY catalog was dropped — they are only ever dropped together. */
+  const drops = () => {
+    const counts = catalogs.map((c) => c.invalidate.mock.calls.length);
+    expect(new Set(counts).size).toBe(1);
+    return counts[0];
+  };
+  return { eventBus, fileChangeNotifier, drops, off };
+}
+
+describe('registerCatalogCacheInvalidation', () => {
+  describe('commit-time (FileChangeNotifier)', () => {
+    it('drops the catalogs when a default-branch commit touches Plugins/', () => {
+      const { fileChangeNotifier, drops } = setup();
+      fileChangeNotifier.emit({
+        workspaceId: 'ws',
+        branch: DEFAULT_BRANCH,
+        paths: [`${KB_DIR}/Plugins/Engineering/coding/SKILL.md`],
+        byUser: USER,
+      });
+      expect(drops()).toBe(1);
+    });
+
+    it('ignores commits on other branches, and commits outside Plugins/', () => {
+      const { fileChangeNotifier, drops } = setup();
+      fileChangeNotifier.emit({
+        workspaceId: 'ws',
+        branch: 'feature/x',
+        paths: [`${KB_DIR}/Plugins/Engineering/coding/SKILL.md`],
+        byUser: USER,
+      });
+      fileChangeNotifier.emit({
+        workspaceId: 'ws',
+        branch: DEFAULT_BRANCH,
+        paths: [`${KB_DIR}/KnowledgeBase/Note.md`],
+        byUser: USER,
+      });
+      expect(drops()).toBe(0);
+    });
+  });
+
+  describe("the default branch's tree changed", () => {
+    /**
+     * The bug this exists for: approving a proposed skill closed its change
+     * request (so it left the pending shelf at once) while the released catalog
+     * kept serving its pre-merge scan, and the card vanished from the library
+     * until the TTL ran out.
+     *
+     * One test, because the subscriber sees ONE signal: the merge reaches here
+     * as the `fs-tree-changed` its post-merge pull emits, exactly as a
+     * working-tree write does — NOT as a `change-request-merged` special
+     * case. That a pull of the default workspace actually emits this event
+     * (only after it resolves, and only when it changed the tree's content) is the emitter's
+     * own contract, pinned in workflow.service.releaseLock.test.ts under
+     * "the tree-change announcement".
+     */
+    it('drops the catalogs when the default tree changes (write or post-merge pull alike)', () => {
+      const { eventBus, drops } = setup();
+      eventBus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws', branch: DEFAULT_BRANCH });
+      expect(drops()).toBe(1);
+    });
+
+    it('drops them when a diverged workspace is reconciled', () => {
+      const { eventBus, drops } = setup();
+      eventBus.emit({ kind: 'git-sync-recovered', workspaceId: 'ws', branch: DEFAULT_BRANCH });
+      expect(drops()).toBe(1);
+    });
+
+    it('ignores both events on another branch', () => {
+      const { eventBus, drops } = setup();
+      eventBus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws', branch: 'feature/x' });
+      eventBus.emit({ kind: 'git-sync-recovered', workspaceId: 'ws', branch: 'feature/x' });
+      expect(drops()).toBe(0);
+    });
+
+    it('drops them BEFORE the event reaches a browser session', () => {
+      const { eventBus, drops } = setup();
+      const seenAtPush: number[] = [];
+      eventBus.subscribe({
+        sessionId: 's1',
+        userId: 'u1',
+        // `fs-tree-changed` is workspace-scoped, so a session only receives
+        // it while focused on that workspace.
+        getFocusedWorkspaceId: () => 'ws',
+        // The browser reloads the library off this event; if the caches were
+        // still warm here, the reload would re-read the stale catalog.
+        push: () => seenAtPush.push(drops()),
+      });
+      eventBus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws', branch: DEFAULT_BRANCH });
+      expect(seenAtPush).toEqual([1]);
+    });
+
+    it('does not drop them when a merge fails', () => {
+      const { eventBus, drops } = setup();
+      eventBus.emit({
+        kind: 'change-request-merge-failed',
+        forUserId: 'u1',
+        number: 42,
+        reason: 'conflicts',
+        conflicts: true,
+      });
+      expect(drops()).toBe(0);
+    });
+  });
+
+  it('detaches every subscription on unsubscribe', () => {
+    const { eventBus, fileChangeNotifier, drops, off } = setup();
+    off();
+    eventBus.emit({ kind: 'change-request-merged', number: 42 });
+    eventBus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws', branch: DEFAULT_BRANCH });
+    fileChangeNotifier.emit({
+      workspaceId: 'ws',
+      branch: DEFAULT_BRANCH,
+      paths: [`${KB_DIR}/Plugins/Engineering/coding/SKILL.md`],
+      byUser: USER,
+    });
+    expect(drops()).toBe(0);
+  });
+});

package/src/core/catalog-cache-invalidation.ts

@@ -0,0 +1,92 @@
+import { DEFAULT_BRANCH, PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
+import type { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
+import type { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+
+/**
+ * A catalog that scans the DEFAULT branch's working tree and caches the result
+ * behind a TTL — the skill catalog, the tool-manual catalog, the plugin index.
+ * All three answer the same question ("what is released?") off the same folder,
+ * so they go stale together and are dropped together.
+ */
+export interface InvalidatableCatalog {
+  invalidate(): void;
+}
+
+/**
+ * Every way a released catalog can go stale, wired in one place.
+ *
+ * The TTL inside each catalog is a backstop, not the freshness mechanism: at a
+ * minute wide it is far longer than the gap between "the user did the thing"
+ * and "the user looks for the result". These three subscribers are what make
+ * the next read see the change instead of the previous minute's answer.
+ *
+ * Returns an unsubscribe that detaches all three.
+ */
+export function registerCatalogCacheInvalidation(deps: {
+  eventBus: WorkflowEventBus;
+  fileChangeNotifier: FileChangeNotifier;
+  /** The KB folder inside the workspace — `paths` are workspace-relative. */
+  kbDirName: string;
+  catalogs: InvalidatableCatalog[];
+}): () => void {
+  const { eventBus, fileChangeNotifier, kbDirName, catalogs } = deps;
+  const invalidateAll = () => {
+    for (const c of catalogs) c.invalidate();
+  };
+
+  // Subscriber A — COMMIT-time freshness: a committed change drops the affected
+  // caches immediately instead of waiting out their TTLs. The catalogs are
+  // global but read the DEFAULT branch only, so only default-branch changes
+  // under their folders matter. (The kb-graph id-index invalidation that used
+  // to live here is registered by the enterprise overlay, next to the kb-graph
+  // service it belongs to — the caches are independent, so the split preserves
+  // behavior.)
+  const offFiles = fileChangeNotifier.onFilesChanged(({ branch, paths }) => {
+    if (branch !== DEFAULT_BRANCH) return;
+    // Skills, tools, the plugin index and the link index all read `Plugins/`
+    // or `Skills/`, so one touch check drives every cache. An access grant
+    // lands as a default-branch change to `Plugins/<plugin>/access.md` or a
+    // skill folder's `access.md`, so this is also what makes a newly-granted
+    // plugin or link unlock within one round-trip instead of one TTL. Both
+    // names are live bindings (a deployment may rename the roots), hence read
+    // per event rather than captured.
+    if (
+      paths.some(
+        (p) => p.startsWith(`${kbDirName}/${PLUGINS_DIR}/`) || p.startsWith(`${kbDirName}/${SKILLS_DIR}/`),
+      )
+    ) {
+      invalidateAll();
+    }
+  });
+
+  // Subscriber B — the DEFAULT branch's tree changed under the catalogs.
+  //
+  // `fs-tree-changed` is emitted the moment bytes hit a working tree: by the
+  // workspace routes when someone writes a file, and by `pullWorkspace` when a
+  // pull rewrites the default workspace — a merge landing an approved skill,
+  // the non-fast-forward recovery ladder, a plain sync from the remote. That
+  // is deliberately ONE signal rather than one per occasion: the catalogs do
+  // not care which path rewrote the tree, only that it is no longer the tree
+  // they scanned. Enumerating the occasions instead (a subscriber for merges,
+  // another for recoveries) left every path nobody had thought of yet serving
+  // a stale catalog for a full TTL — which is exactly how the merge case got
+  // missed.
+  //
+  // `git-sync-recovered` is the same fact arriving by the other road: a
+  // workspace that had diverged from origin has been reconciled, so its tree
+  // moved. The pull inside that recovery announces itself, but the recovery
+  // can also complete by paths that do not run one, and a catalog left holding
+  // a scan of the diverged tree is the failure this exists to prevent.
+  const offEmit = eventBus.onEmit((event) => {
+    if (event.kind !== 'fs-tree-changed' && event.kind !== 'git-sync-recovered') return;
+    // Both events declare `branch`, so no `in` guard: the kind check above has
+    // already narrowed the union to the two that carry one.
+    if (event.branch !== DEFAULT_BRANCH) return;
+    invalidateAll();
+  });
+
+  return () => {
+    offFiles();
+    offEmit();
+  };
+}

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

@@ -20,7 +20,7 @@ import {
 import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
 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 { registerSkillsTools, createSkillsRoutes, createSkillAccessRequestRoutes } from '../modules/skills/index.js';
 import { createPluginsRoutes } from '../modules/plugins/index.js';
 import type { SessionOntologyGate } from '../modules/workspace/session-ontology.gate.js';
 import {
@@ -33,7 +33,17 @@ import { createGroupsAdminRoutes } from '../modules/access/groups-admin.routes.j
 import { createUpdateCheckRoutes } from '../modules/update-check/update-check.routes.js';
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createSetupRoutes } from '../modules/settings/setup.routes.js';
-import { DEFAULT_BRANCH, PROTECTED_BRANCHES, type AuthUser } from '@bevel-software/platform-shared';
+import {
+  createKbSyncRoutes,
+  isSyncRawBodyPath,
+  SYNC_RESPONSE_HEADER,
+} from '../modules/kb-sync/kb-sync.routes.js';
+import { createMarketplaceGitRoutes } from '../modules/marketplace/index.js';
+import {
+  createGitHubFacadeAdminRoutes,
+  createGitHubFacadeRoutes,
+} from '../modules/marketplace/github-facade/index.js';
+import { DEFAULT_BRANCH, PROTECTED_BRANCHES, currentKbLayout, type AuthUser } from '@bevel-software/platform-shared';
 import { GIT_SHA } from '../version.js';
 import type { CoreServices } from './create-core-services.js';
 
@@ -132,7 +142,9 @@ export async function createCoreServer(
     cors({
       origin: true,
       credentials: true,
-      exposedHeaders: ['Mcp-Session-Id', 'Mcp-Protocol-Version', 'WWW-Authenticate'],
+      // `SYNC_RESPONSE_HEADER` is how the browser tells the sync endpoint's
+      // own 503 from a reverse proxy's — see `kb-sync.routes.ts`.
+      exposedHeaders: ['Mcp-Session-Id', 'Mcp-Protocol-Version', 'WWW-Authenticate', SYNC_RESPONSE_HEADER],
     }),
   );
   // Global JSON body parser. Some overlay routes carry a whole document dump
@@ -141,10 +153,13 @@ export async function createCoreServer(
   // parse once the first has run, so without this the 10 MB global limit would
   // shadow the route's larger limit and 413 a large-but-valid upload before it
   // ever reaches the route).
+  // The sync routes (`/api/sync` and `/api/sync/<branch>`) read their body as
+  // raw bytes: one of their credentials is an HMAC over exactly what arrived,
+  // which a parsed-and-reserialised body cannot reproduce.
   const jsonExemptPaths = new Set(ext.jsonParserExemptPaths ?? []);
   const globalJson = express.json({ limit: '10mb' });
   app.use((req, res, next) => {
-    if (jsonExemptPaths.has(req.path)) return next();
+    if (jsonExemptPaths.has(req.path) || isSyncRawBodyPath(req.path)) return next();
     return globalJson(req, res, next);
   });
 
@@ -178,6 +193,13 @@ export async function createCoreServer(
   const mcpResourceUrl = new URL('/api/mcp', core.config.publicBackendUrl);
   mcpResourceUrl.username = '';
   mcpResourceUrl.password = '';
+  /** The remote-sync address the setup status publishes for admins to paste into a hook. */
+  const syncUrl = new URL('/api/sync', core.config.publicBackendUrl);
+  syncUrl.username = '';
+  syncUrl.password = '';
+  const marketplaceGitUrl = new URL(`/git/${core.marketplaceRepo.repoName}`, core.config.publicBackendUrl);
+  marketplaceGitUrl.username = '';
+  marketplaceGitUrl.password = '';
 
   /**
    * The handful of facts the browser needs BEFORE it can render anything, and
@@ -199,6 +221,18 @@ export async function createCoreServer(
         defaultBranch: DEFAULT_BRANCH,
         protectedBranches: [...PROTECTED_BRANCHES],
       },
+      /**
+       * The three renameable KB roots, for the same reason as the branch
+       * model: the file tree, the library router and every path rule read
+       * them, and they used to be compile-time constants.
+       */
+      kbLayout: currentKbLayout(),
+      /**
+       * The per-user marketplace git remote (see modules/marketplace). Same
+       * derivation as `mcpUrl`: our address, userinfo stripped — the caller
+       * adds their own connection key.
+       */
+      marketplaceGitUrl: marketplaceGitUrl.toString(),
       /**
        * The same value the OAuth metadata publishes (see `mcpResourceUrl`).
        *
@@ -217,6 +251,36 @@ export async function createCoreServer(
     });
   });
 
+  // The per-user marketplace as a git remote. Outside `/api` and ahead of
+  // every JWT mount: it authenticates with a connection key in HTTP Basic
+  // (what `git clone https://key:<k>@…` sends), and git's own http-backend
+  // serves the protocol. See modules/marketplace.
+  app.use(
+    '/git',
+    createMarketplaceGitRoutes({
+      repo: core.marketplaceRepo,
+      keys: core.externalApiKeyService,
+      mountPath: '/git',
+    }),
+  );
+
+  // The SAME marketplace as a GitHub Enterprise consumer (claude.ai, Cowork)
+  // fetches it: the GitHub-shaped OAuth pair at /login/oauth/* and the REST
+  // calls at /api/v3/*, reading the same per-user tree by the same connection
+  // key. At the app root because those paths are GitHub's, and ahead of the
+  // /api JWT mounts because the consumer's backend arrives with a Bearer
+  // key, never a session.
+  app.use(
+    createGitHubFacadeRoutes({
+      facade: core.githubFacade,
+      keys: core.externalApiKeyService,
+      repo: core.marketplaceRepo,
+      owner: 'git',
+      repoName: core.marketplaceRepo.repoName.replace(/\.git$/, ''),
+      publicUrl: core.config.publicBackendUrl,
+    }),
+  );
+
   // Overlay boot-time side effects (startup reconciles, periodic sweeps).
   await ext.onBoot?.(core);
 
@@ -277,6 +341,17 @@ export async function createCoreServer(
     core.mcpResourceMetadataUrl,
   ));
 
+  // Remote sync — `POST /api/sync`, called by a git host's webhook or a
+  // pipeline with the deployment's sync secret (or by an admin's session).
+  // Same reason as MCP for mounting here: a non-JWT bearer must not meet a
+  // protected mount first.
+  app.use('/api', createKbSyncRoutes({
+    kbSync: core.kbSyncService,
+    syncSecret: () => core.settings.resolve('kbSyncSecret'),
+    authService: core.authService,
+    adminAccess: core.adminAccess,
+  }));
+
   // MCP OAuth 2.1 authorization server: /authorize, /token, /register,
   // /revoke + the /.well-known metadata documents (the SDK requires an
   // app-root mount for those paths). Un-authed by design — these endpoints
@@ -431,7 +506,23 @@ export async function createCoreServer(
   app.use(
     '/api',
     core.authMiddleware,
-    createSkillsRoutes(core.skillService, core.pendingSkillsService),
+    createSkillsRoutes(core.skillService, core.pendingSkillsService, core.pluginLinkIndex, core.accessControl),
+  );
+  // Asking for write on a shared skill — the join-request machinery pointed
+  // at a skill folder. Same JWT gate, same fail-closed shape.
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createSkillAccessRequestRoutes({
+      skillService: core.skillService,
+      accessControl: core.accessControl,
+      workflow: core.workflowService,
+      workspaceService: core.workspaceService,
+      joinRequests: core.joinRequestsService,
+      kbDirName: core.kbDirName,
+      resolveUser: async (req) =>
+        req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null,
+    }),
   );
   // Plugin enumeration + join requests. Browser-only (JWT), and fail-closed
   // like every other read surface: plugins the caller cannot access (member,
@@ -446,6 +537,8 @@ export async function createCoreServer(
     core.pluginProvisionService,
     core.kbDirName,
     async (req) => (req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null),
+    core.pluginLinksService,
+    core.pluginRenameService,
   ));
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
@@ -478,7 +571,12 @@ export async function createCoreServer(
   app.use(
     '/api',
     core.authMiddleware,
-    createSetupRoutes(core.settings, core.adminAccess, core.kbStartupRunner),
+    createSetupRoutes(core.settings, core.adminAccess, core.kbStartupRunner, {
+      // Same address family as the MCP endpoint above, userinfo stripped for
+      // the same reason: this string is handed to admins to paste elsewhere.
+      url: syncUrl.toString(),
+      lastSync: () => core.kbSyncService.lastSync(),
+    }),
   );
   app.use('/api', core.authMiddleware, createToolManualsBrowserRoutes(core.toolManualService, {
     service: core.mcpServerEditService,
@@ -495,6 +593,20 @@ export async function createCoreServer(
   app.use('/api', core.authMiddleware, createOAuthConsentRoutes({
     provider: core.mcpOAuthProvider,
     stateSecret: core.config.jwtSecret,
+    facade: {
+      isFacadeRequest: (st) => core.githubFacade.isFacadeRequest(st),
+      clientNameFor: (st) => core.githubFacade.clientNameFor(st),
+      completeConsent: (userId, st) => core.githubFacade.completeConsent(userId, st),
+    },
+  }));
+
+  // What an Owner pastes into Claude's admin settings to register this
+  // deployment as a GitHub Enterprise Server — admins only.
+  app.use('/api', core.authMiddleware, createGitHubFacadeAdminRoutes({
+    credentials: core.githubFacadeCredentials,
+    isAdmin: (email) => core.adminAccess.isAdmin(email),
+    publicUrl: core.config.publicBackendUrl,
+    marketplaceUrl: marketplaceGitUrl.toString(),
   }));
 
   // JWT-protected overlay routes.
@@ -512,7 +624,11 @@ export async function createCoreServer(
       // MCP client parses as JSON → "expected object, received undefined" and
       // the whole connection fails. A clean 404 lets discovery fall through to
       // the variant we do serve. Same reasoning for stray `/api/*` gets.
-      if (req.path.startsWith('/.well-known/') || req.path.startsWith('/api/')) {
+      if (
+        req.path.startsWith('/.well-known/') ||
+        req.path.startsWith('/api/') ||
+        req.path.startsWith('/login/oauth/')
+      ) {
         res.status(404).json({ error: 'Not found' });
         return;
       }