@bevel-software/platform-core-backend 0.20.0 → 0.22.0

package/src/modules/settings/setup.routes.ts

@@ -23,18 +23,34 @@ import {
   type RepositoryConnection,
 } from './connection-check.js';
 import {
-  configureBranchModel,
-  configureKbLayout,
-  isBranchModelConfigured,
   isDefaultKbLayout,
   validateBranchModel,
   validateKbLayout,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { failureOf, type GitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { listRootFolders, pickListingBranch } from './git-root-folders.js';
+import { MANAGED_DEFAULT_BRANCH } from './managed-repository.js';
+import { GIT_MODES, type GitHubAppRepository, type RepositorySource } from './repository-source.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 
+/**
+ * What setup needs of the ways a deployment can be given its repository:
+ * the source every reader of the repository asks, and the one thing a mode
+ * has to have DONE before a save that chooses it may go through.
+ */
+export interface RepositorySetup {
+  source: RepositorySource;
+  /** Create the repository the deployment keeps for itself, if it is not there. Never touches one that is. */
+  ensureManaged(initialBranch: string): Promise<void>;
+  /**
+   * The connection to GitHub through a GitHub App. Absent, that way is not
+   * offered, and a save that names it is refused.
+   */
+  githubApp?: Pick<GitHubAppRepository, 'url' | 'answered' | 'prepare' | 'token' | 'permits'>;
+}
+
 /** Which name a host expects beside the token when none is configured. */
 const DEFAULT_GIT_USERNAME = 'x-access-token';
 
@@ -105,6 +121,12 @@ export function createSetupRoutes(
     /** That failure classified, for the setup screen; absent, the message is read instead. */
     lastFailureKind?(): GitFailure | null;
   },
+  /**
+   * The knowledge base's context as the running graph holds it: the save
+   * that completes setup applies the branch model and the layout to it, so
+   * every service reads the admin's answer without a restart.
+   */
+  kb: KbContext,
   /**
    * The remote-sync facts the Deployment page shows beside the sync secret:
    * the address a webhook or pipeline must call, and what the last call did.
@@ -134,8 +156,14 @@ export function createSetupRoutes(
   checkOidc: (config: OidcConfiguration) => Promise<OidcCheck> = checkOidcConfiguration,
   /** The issuer-only half, for a test with no application id or secret yet. */
   checkIssuer: (issuerUrl: string) => Promise<IssuerCheck> = (url) => checkOidcIssuer(url),
+  /**
+   * The ways a deployment can be given its repository. Absent, there is the
+   * one there always was: an address and a token, read from the settings.
+   */
+  repository?: RepositorySetup,
 ): express.Router {
   const router = express.Router();
+  const source = repository?.source;
 
   /**
    * Why the last setup-time run of the KB startup phase FAILED, or null. While
@@ -180,7 +208,30 @@ export function createSetupRoutes(
   };
   /** The app-gate answer: settings complete AND the KB phase settled clean, whoever ran it. */
   const kbReady = () =>
-    isComplete(settings) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
+    isComplete(settings, kb, source) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
+
+  /**
+   * Which ways of having a repository this deployment offers and which one
+   * it is on, for the setup screen. `mode` is the one IN EFFECT, inferred
+   * for a deployment that never chose; `chosen` is the one the settings
+   * say, which differs from it between a move and the restart the move
+   * owes. The screen opens on what was chosen, says a restart is pending
+   * when the two differ, and offers the first of `modes` to a deployment
+   * that has none. `pinned` names the variable that chose for the
+   * deployment, when one did. Nothing at all from a mount without the
+   * choice, which the screen reads as the one way there was.
+   */
+  const repositoryStatus = () =>
+    source
+      ? {
+          repository: {
+            mode: source.mode(),
+            chosen: source.chosen(),
+            ...(settings.sourceOf('gitMode') === 'env' ? { pinned: 'GIT_MODE' } : {}),
+            modes: GIT_MODES.filter((mode) => mode !== 'github-app' || repository?.githubApp !== undefined),
+          },
+        }
+      : {};
 
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
@@ -215,9 +266,10 @@ export function createSetupRoutes(
     }
     res.json({
       complete: kbReady(),
-      awaitingRestart: awaitingRestart(settings),
+      awaitingRestart: awaitingRestart(settings, kb, source),
       isAdmin: true,
       settings: settings.describe(),
+      ...repositoryStatus(),
       oidcVerification: await settings.oidcVerification(),
       ...(kbInit ? { kbInit } : bootFailure() !== null ? { kbInit: bootFailureKind() } : {}),
       ...(sync ? { sync: { url: sync.url, last: sync.lastSync() } } : {}),
@@ -261,7 +313,13 @@ export function createSetupRoutes(
       // save that flips it false→true — whichever field arrives last — is the
       // one that must run the KB startup phase, regardless of which save
       // configured the branch model.
-      const wasComplete = isComplete(settings);
+      const wasComplete = isComplete(settings, kb, source);
+      // A different question, asked of the GATE: whether anyone is being
+      // served. Settings that are answered are not a deployment that works
+      // — one whose first clone failed has answered everything and serves
+      // nobody.
+      const wasServing = kbReady();
+      nameBranchesOfManagedRepository(entries);
       if (!(await connectionHoldsFor(entries, wasComplete, res))) return;
       const oidc = await signInHoldsFor(entries, res);
       if (!oidc) return;
@@ -273,7 +331,35 @@ export function createSetupRoutes(
       if (oidc.record) {
         await settings.recordOidcVerification(oidc.record.state, oidc.record.credentials);
       }
-      const { restartRequired, restartKeys } = await settings.save(entries, req.userId ?? null);
+      const saved = await settings.save(entries, req.userId ?? null);
+      /**
+       * A deployment that was not serving has nothing on the mode it had:
+       * the mode chosen takes effect now, and the startup phase below is
+       * what a restart would have run. One that WAS serving stays on the
+       * mode it is on, working copies and credential alike, until it is
+       * started again.
+       *
+       * SERVING, not answered. The pin protects what is running on the
+       * mode in effect, and behind a shut gate nothing is: a first run
+       * whose initialisation failed, a boot that found its repository
+       * unreachable. Pinned there, the way out of a repository that does
+       * not work would be closed — the admin chooses another, the retry
+       * below runs against the one that just failed, and the screen asks
+       * for a restart that changes nothing.
+       */
+      if (source && !wasServing) source.takeEffect();
+      /**
+       * The restart the mode owes is read off the two modes themselves, not
+       * off what this save wrote: it is owed for as long as the mode chosen
+       * is not the one in effect, whichever save chose it, and no longer
+       * once a save chooses the mode in effect back.
+       */
+      const modePending = source !== undefined && source.chosen() !== source.mode();
+      const restartKeys = [
+        ...saved.restartKeys.filter((key) => key !== 'gitMode'),
+        ...(modePending ? ['gitMode'] : []),
+      ];
+      const restartRequired = restartKeys.length > 0;
       /** Whether this save put the stored folder names into the running process. */
       let layoutApplied = false;
       /** Whether this save put the stored branch model into the running process. */
@@ -292,13 +378,13 @@ export function createSetupRoutes(
        * capturing it at construction, which is what makes applying it here
        * enough.
        */
-      if (!isBranchModelConfigured()) {
+      if (!kb.isBranchModelConfigured()) {
         const model = {
           defaultBranch: settings.resolve('defaultBranch'),
           protectedBranches: settings.resolve('protectedBranches'),
         };
         if (!validateBranchModel(model)) {
-          configureBranchModel(model);
+          kb.applyBranchModel(model);
           branchModelApplied = true;
         }
       }
@@ -316,7 +402,7 @@ export function createSetupRoutes(
        * on a re-save of a complete, healthy setup: with the gate open,
        * sessions may be live and that is no longer a quiet moment.
        */
-      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings)) {
+      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings, kb, source)) {
         /**
          * The folder names, applied BEFORE the phase for the same reason as
          * the branch model above: they are otherwise applied once at boot, so
@@ -327,10 +413,10 @@ export function createSetupRoutes(
          * the names an earlier setup save applied before a run that failed:
          * the gate never opened, so the retry initializes what is saved now.
          */
-        if (isDefaultKbLayout() || (kbInit !== null && layoutAppliedBySetup)) {
+        if (isDefaultKbLayout(kb.layout) || (kbInit !== null && layoutAppliedBySetup)) {
           const layout = settings.resolveKbLayout();
           if (!validateKbLayout(layout)) {
-            configureKbLayout(layout);
+            kb.applyLayout(layout);
             layoutApplied = true;
             layoutAppliedBySetup = true;
           }
@@ -356,6 +442,7 @@ export function createSetupRoutes(
           const raw = initErr instanceof Error ? initErr.message : String(initErr);
           const msg = redactSecret(raw, [
             settings.resolve('gitToken'),
+            source?.credentials.token() ?? '',
             ...urlQuerySecrets(settings.resolve('kbRepoUrl')),
           ]);
           log.error(`KB initialization failed after setup completed: ${msg}`);
@@ -382,8 +469,9 @@ export function createSetupRoutes(
               )
             : restartRequired,
         complete: kbReady(),
-        awaitingRestart: awaitingRestart(settings),
+        awaitingRestart: awaitingRestart(settings, kb, source),
         settings: settings.describe(),
+        ...repositoryStatus(),
         oidcVerification: await settings.oidcVerification(),
       });
     } catch (err) {
@@ -398,6 +486,101 @@ export function createSetupRoutes(
     }
   }
 
+  /**
+   * A repository the deployment keeps for itself is new, and empty, and has
+   * no branches for anyone to look up: the branch model is ours to name. It
+   * is named only when nobody has — an admin's own answer, or one the
+   * environment supplies, stands. Every other mode has a repository that
+   * already exists, whose branches are asked for, never guessed.
+   */
+  function nameBranchesOfManagedRepository(entries: Record<string, string>): void {
+    if (!source) return;
+    const after = settings.resolveAfter(entries);
+    if (source.mode(after) !== 'managed') return;
+    if (after('defaultBranch') || after('protectedBranches')) return;
+    entries.defaultBranch = MANAGED_DEFAULT_BRANCH;
+    entries.protectedBranches = MANAGED_DEFAULT_BRANCH;
+  }
+
+  /**
+   * The same rule for a repository reached through a GitHub App: a saved
+   * connection is one GitHub has accepted for reading and writing, asked
+   * with the token git will present, which is the installation's.
+   *
+   * That token is also what keeps the repository's NAME honest. It is the
+   * one part of this connection an admin types, and a name the installation
+   * does not reach is refused here by GitHub, not by a list of ours.
+   *
+   * The repository has just said what it calls its trunk, so a deployment
+   * with no branch model is given that one: the same answer the setup
+   * screen fills in for a repository reached by its address.
+   */
+  async function githubConnectionHoldsFor(
+    setup: RepositorySetup,
+    entries: Record<string, string>,
+    after: (key: string) => string,
+    wasComplete: boolean,
+    res: express.Response,
+  ): Promise<boolean> {
+    const refuse = (problem: string, field = 'githubRepository') => {
+      res.status(400).json({ error: problem, problems: { [field]: problem } });
+      return false;
+    };
+    const app = setup.githubApp;
+    if (!app) return refuse('This deployment cannot connect to GitHub through a GitHub App.', 'gitMode');
+    if (!app.answered(after)) {
+      return refuse(
+        after('githubRepository')
+          ? 'Connect GitHub before choosing a repository.'
+          : 'Choose the repository the knowledge base lives in.',
+      );
+    }
+    const url = app.url(after);
+    const unanswered =
+      validateBranchModel({ defaultBranch: after('defaultBranch'), protectedBranches: after('protectedBranches') }) !== null;
+    // Against what is CHOSEN now, not what is in effect: a repository that
+    // was proven by the save that chose it is not proven again by the next.
+    const stored = (key: string) => settings.resolve(key);
+    const changes = setup.source.chosen() !== 'github-app' || url !== setup.source.url(stored);
+    if (!changes && (wasComplete || unanswered)) return true;
+    // BEFORE GitHub is asked anything with the installation token: that
+    // token reaches every repository the installation covers, and would
+    // answer for one the person connecting it could never have written to.
+    if (!app.permits(after('githubRepository'), after)) {
+      log.warn('a repository was named that the person who connected GitHub could not push to');
+      return refuse(
+        'Choose a repository your own GitHub account can write to. If this one should be, press “Refresh the list” so it is brought up to date.',
+      );
+    }
+    try {
+      await app.prepare({ asked: true });
+    } catch (err) {
+      log.error('GitHub gave no token for the installation:', { detail: err instanceof Error ? err.message : String(err) });
+    }
+    const token = app.token();
+    if (!token) {
+      return refuse('GitHub gave this deployment no access. The app may have been uninstalled: connect it again.', 'gitMode');
+    }
+    const check = await checkConnection({ url, token, username: DEFAULT_GIT_USERNAME });
+    if (check.outcome !== 'connected') {
+      return refuse(
+        check.outcome === 'read-only'
+          ? 'The GitHub App can read that repository but not write to it. Grant it write access to the repository’s contents.'
+          : check.reason === 'unreachable'
+            ? 'GitHub could not be reached. Try again shortly.'
+            : 'The GitHub App cannot reach that repository. Add the repository to the app’s installation on GitHub.',
+      );
+    }
+    if (!after('defaultBranch') && !after('protectedBranches')) {
+      const trunk = check.defaultBranch || check.branches[0] || (check.empty ? MANAGED_DEFAULT_BRANCH : '');
+      if (trunk) {
+        entries.defaultBranch = trunk;
+        entries.protectedBranches = trunk;
+      }
+    }
+    return true;
+  }
+
   /**
    * A SAVED CONNECTION IS ONE THE HOST HAS ACCEPTED FOR READING AND WRITING.
    *
@@ -423,6 +606,25 @@ export function createSetupRoutes(
     res: express.Response,
   ): Promise<boolean> {
     const after = settings.resolveAfter(entries);
+    if (repository && repository.source.mode(after) === 'managed') {
+      // Nothing to prove to a host: the repository is the deployment's own.
+      // What has to hold is that it EXISTS before the save that points
+      // everything at it, so a disk that cannot take it refuses the choice
+      // instead of failing the first clone.
+      try {
+        await repository.ensureManaged(after('defaultBranch') || MANAGED_DEFAULT_BRANCH);
+        return true;
+      } catch (err) {
+        log.error('the managed repository could not be created:', { err });
+        const problem =
+          'The repository could not be created on this deployment’s storage. Check that its backups folder is writable, or connect a repository of your own.';
+        res.status(400).json({ error: problem, problems: { gitMode: problem } });
+        return false;
+      }
+    }
+    if (repository && repository.source.mode(after) === 'github-app') {
+      return githubConnectionHoldsFor(repository, entries, after, wasComplete, res);
+    }
     const now: RepositoryConnection = {
       url: settings.resolve('kbRepoUrl'),
       token: settings.resolve('gitToken'),
@@ -759,8 +961,12 @@ export function createSetupRoutes(
  * deployment signs in perfectly well without it, and gating on it would lock
  * an admin out of the screen where they would set it up.
  */
-export function settingsAnswered(settings: DeploymentSettingsService): boolean {
-  const kb = Boolean(settings.resolve('kbRepoUrl') && settings.resolve('gitToken'));
+export function settingsAnswered(
+  settings: DeploymentSettingsService,
+  /** What answers for the repository. Absent: an address and a token, the one way there was. */
+  source?: Pick<RepositorySource, 'answered'>,
+): boolean {
+  const kb = source ? source.answered() : Boolean(settings.resolve('kbRepoUrl') && settings.resolve('gitToken'));
   const branches =
     validateBranchModel({
       defaultBranch: settings.resolve('defaultBranch'),
@@ -784,11 +990,19 @@ export function settingsAnswered(settings: DeploymentSettingsService): boolean {
  * that puts it there. {@link awaitingRestart} is what tells the screen to ask
  * for one rather than claim a field is missing.
  */
-export function isComplete(settings: DeploymentSettingsService): boolean {
-  return settingsAnswered(settings) && isBranchModelConfigured();
+export function isComplete(
+  settings: DeploymentSettingsService,
+  kb: Pick<KbContext, 'isBranchModelConfigured'>,
+  source?: Pick<RepositorySource, 'answered'>,
+): boolean {
+  return settingsAnswered(settings, source) && kb.isBranchModelConfigured();
 }
 
 /** Answered, but not yet in effect: everything is stored, the process is stale. */
-export function awaitingRestart(settings: DeploymentSettingsService): boolean {
-  return settingsAnswered(settings) && !isBranchModelConfigured();
+export function awaitingRestart(
+  settings: DeploymentSettingsService,
+  kb: Pick<KbContext, 'isBranchModelConfigured'>,
+  source?: Pick<RepositorySource, 'answered'>,
+): boolean {
+  return settingsAnswered(settings, source) && !kb.isBranchModelConfigured();
 }

package/src/modules/skills/__tests__/allowed-tools-check.test.ts

@@ -7,6 +7,7 @@ import {
 } from '../allowed-tools-check.js';
 import type { UtcpTool } from '../../tool-registry/tool.contract.js';
 import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const visible: VisibleTools = {
   core: ['read_file', 'get_skill', 'list_skills'],
@@ -110,10 +111,10 @@ describe('checkAllowedTools', () => {
 
 describe('skillFileRepoPath', () => {
   test('recognises skill files under the plugin and skills roots only', () => {
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
-    expect(skillFileRepoPath('knowledge-base', './knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Data/SKILL.md')).toBeNull();
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
+    expect(skillFileRepoPath(testKbContext(),'./knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Data/SKILL.md')).toBeNull();
   });
 });
 
@@ -138,7 +139,7 @@ describe('AllowedToolsChecker', () => {
           }
         : null,
   };
-  const checker = new AllowedToolsChecker(registry, manuals, 'knowledge-base');
+  const checker = new AllowedToolsChecker(registry, manuals, testKbContext());
 
   const skill = (tools: string) => `---\nname: rfi\ndescription: RFI.\nallowed-tools: ${tools}\n---\n\n# RFI\n`;
 
@@ -160,7 +161,7 @@ describe('AllowedToolsChecker', () => {
     const broken = new AllowedToolsChecker(
       { listExternal: async () => { throw new Error('down'); } },
       manuals,
-      'knowledge-base',
+      testKbContext(),
     );
     await expect(
       broken.checkSave('a@x.com', 'knowledge-base/Plugins/Sales/rfi/SKILL.md', skill('hubspot.serch')),
@@ -168,7 +169,7 @@ describe('AllowedToolsChecker', () => {
   });
 
   test('a capped capability list is treated as unknown, never as proof of absence', async () => {
-    const capped = new AllowedToolsChecker(registry, manuals, 'knowledge-base', 1);
+    const capped = new AllowedToolsChecker(registry, manuals, testKbContext(), 1);
     expect(await capped.check('a@x.com', ['hubspot.whatever'])).toEqual([]);
   });
 
@@ -179,7 +180,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     expect(entries(await spying.check('alice@example.com', ['hubspot.serch']))).toEqual(['hubspot.serch']);
     expect(listExternal).toHaveBeenCalledWith({ userEmail: 'alice@example.com' });
@@ -193,7 +194,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     const results = await spying.checkSaves('a@x.com', [
       { path: 'knowledge-base/Plugins/Sales/rfi/SKILL.md', content: skill('hubspot.serch') },
@@ -214,7 +215,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     expect(await spying.check('a@x.com', ['Bash', 'Read', 'Bash(git:*)', 'mcp__github__create_issue', 'shell'])).toEqual([]);
     expect(listExternal).not.toHaveBeenCalled();

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -19,6 +19,7 @@ import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/too
 import { registerSkillsTools } from '../skills.tools.js';
 import type { ISkillService } from '../skills.contract.js';
 import { AllowedToolsChecker } from '../allowed-tools-check.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The agent surfaces end to end: a SKILL.md written through the file tools
@@ -41,7 +42,7 @@ const checker = new AllowedToolsChecker(
       capabilities: [{ name: 'search', description: null }],
     }),
   },
-  KB_DIR,
+  testKbContext({ kbDirName: KB_DIR }),
 );
 
 /** What the tool handed the service on its last `getSkill` — the tool's one job is to pass it on. */
@@ -109,8 +110,8 @@ async function start(): Promise<string> {
   const router = express.Router();
   registerWorkspaceTools(
     registry, router, fakeAuth, toolHandler,
-    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-    { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+    { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
     new RoutineWritePolicyService(),
     {} as never,
     checker,

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

@@ -5,6 +5,7 @@ import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ISkillService, SkillSummary } from '../skills.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The half of the catalog that is NOT on the default branch.
@@ -77,7 +78,7 @@ function harness(opts: {
     listChangeRequests: async () => opts.crs,
   } as unknown as IWorkflowService;
 
-  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow);
+  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow, testKbContext());
 }
 
 const ADMIN_WRITES = {
@@ -210,6 +211,7 @@ describe('PendingSkillsService', () => {
       {} as unknown as IAccessControl,
       { listSkills: async () => [] } as unknown as ISkillService,
       workflow,
+      testKbContext(),
     );
     await expect(svc.listPendingSkills(AUTHOR)).resolves.toEqual([]);
   });

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -11,6 +11,7 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { JoinRequestsService } from '../../plugins/join-requests.service.js';
 import type { ISkillService } from '../skills.contract.js';
 import { createSkillAccessRequestRoutes } from '../skill-access-requests.routes.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The branch probe behind an access request: the listing is used to PROVE a
@@ -26,15 +27,19 @@ const FOLDER = 'Skills/Eng/deploy';
 
 async function makeHarness(listBranches: IWorkflowService['listBranches']) {
   const workflow = {
-    listChangeRequestsAuthoredBy: vi.fn(async () => []),
+    listChangeRequests: vi.fn(async () => []),
     listBranches: vi.fn(listBranches),
     createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
+    deleteBranch: vi.fn(async () => undefined),
     commitChanges: vi.fn(async () => null),
     openChangeRequest: vi.fn(async () => ({ number: 42 })),
+    getChangeRequestDetail: vi.fn(async () => ({ body: '' })),
   } as unknown as IWorkflowService;
   const workspaceService = {
     getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: workspaceIdForBranch(branch) })),
     readFile: vi.fn(async () => '---\n---\nwrite:\n  - Eve <eve@x.io>\n'),
+    readFileAtRef: vi.fn(async () => null),
+    ensureRemotesFetched: vi.fn(async () => undefined),
     writeFile: vi.fn(async () => undefined),
   } as unknown as WorkspaceService;
   const accessControl = { canWrite: vi.fn(async () => false) } as unknown as IAccessControl;
@@ -52,7 +57,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
       workflow,
       workspaceService,
       joinRequests: { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService,
-      kbDirName: KB,
+      kb: testKbContext({ kbDirName: KB }),
       resolveUser: async () => MIA,
     }),
   );

package/src/modules/skills/__tests__/skills.routes.warnings.test.ts

@@ -5,6 +5,7 @@ import '../../auth/auth.middleware.js'; // Express Request.userEmail augmentatio
 import { createSkillsRoutes } from '../skills.routes.js';
 import type { ISkillService } from '../skills.contract.js';
 import type { IAllowedToolsChecker } from '../allowed-tools-check.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The browser's skill read carries the same `allowed-tools` warnings as
@@ -42,7 +43,7 @@ async function start(checker?: IAllowedToolsChecker): Promise<string> {
     req.userEmail = EMAIL;
     next();
   });
-  app.use('/api', createSkillsRoutes(skillService, undefined, undefined, undefined, checker));
+  app.use('/api', createSkillsRoutes(skillService, testKbContext(), undefined, undefined, undefined, checker));
   server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });

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

@@ -13,6 +13,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { GitService } from '../../workflow/git/git.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -53,7 +54,7 @@ describe('SkillService', () => {
   } as unknown as IAccessControl;
 
   const svc = (access: IAccessControl = allowAll) =>
-    new SkillService(workspaceService, access, KB_DIR, new NodeFs());
+    new SkillService(workspaceService, access, testKbContext({ kbDirName: KB_DIR }), new NodeFs());
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
@@ -377,7 +378,7 @@ describe('SkillService', () => {
 
     const versioned = (access: IAccessControl = allowAll) => {
       const service = svc(access);
-      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), KB_DIR));
+      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), testKbContext({ kbDirName: KB_DIR })));
       return service;
     };
 

package/src/modules/skills/allowed-tools-check.ts

@@ -1,5 +1,5 @@
-import { PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IToolRegistry } from '../tool-registry/tool.contract.js';
 import {
   EXTERNAL_KB_MANUAL_NAME,
@@ -236,11 +236,12 @@ function editDistance(a: string, b: string): number {
  * Accepts the workspace spelling (`<kbDirName>/Plugins/…`) the save
  * surfaces receive.
  */
-export function skillFileRepoPath(kbDirName: string, workspacePath: string): string | null {
+export function skillFileRepoPath(kb: Pick<KbContext, 'kbDirName' | 'layout'>, workspacePath: string): string | null {
   const parts = workspacePath.split('/').filter((p) => p && p !== '.');
-  if (parts[0] === kbDirName) parts.shift();
+  if (parts[0] === kb.kbDirName) parts.shift();
   if (parts.length < 3 || parts[parts.length - 1] !== 'SKILL.md') return null;
-  return parts[0] === PLUGINS_DIR || parts[0] === SKILLS_DIR ? parts.join('/') : null;
+  const { pluginsDir, skillsDir } = kb.layout;
+  return parts[0] === pluginsDir || parts[0] === skillsDir ? parts.join('/') : null;
 }
 
 /** What the save surfaces and `get_skill` depend on. */
@@ -267,7 +268,7 @@ export class AllowedToolsChecker implements IAllowedToolsChecker {
   constructor(
     private readonly registry: Pick<IToolRegistry, 'listExternal'>,
     private readonly manuals: Pick<IToolManualService, 'listAccessible' | 'getDetail'>,
-    private readonly kbDirName: string,
+    private readonly kb: Pick<KbContext, 'kbDirName' | 'layout'>,
     /**
      * The cap `getDetail` applies to a manual's capabilities. Taken from the
      * projection itself: a copy of the number here would silently start
@@ -300,7 +301,7 @@ export class AllowedToolsChecker implements IAllowedToolsChecker {
    * fail because a check could not run).
    */
   private declaredTools(workspacePath: string, content: string): readonly string[] | undefined {
-    if (skillFileRepoPath(this.kbDirName, workspacePath) === null) return undefined;
+    if (skillFileRepoPath(this.kb, workspacePath) === null) return undefined;
     try {
       return parseSkillFrontmatter(content).allowedTools;
     } catch (err) {