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

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -10,6 +10,7 @@ import {
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/tool-manuals.contract.js';
+import type { IConnectionProbeService } from '../connection-probe/connection-probe.contract.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
@@ -21,6 +22,11 @@ export interface SecretsVaultRoutesDeps {
   toolManualService: IToolManualService;
   /** Gates who may set a tool's ADMIN (shared) secrets — writers of the `.tool` file. */
   accessControl: IAccessControl;
+  /**
+   * Verdicts of the last credential PROBE per tool — what makes the difference
+   * between "a key is stored" and "the key works" visible to the UI.
+   */
+  connectionProbe: IConnectionProbeService;
   /** HMAC secret for signing the OAuth `state` (reuse the connector state secret). */
   stateSecret: string;
   /** Public base URL of THIS backend — builds the OAuth redirect URI. */
@@ -69,7 +75,7 @@ export function isSafeReturnPath(returnTo: unknown): returnTo is string {
  * `req.userId` — secrets are private per user. Mounted behind the JWT middleware.
  */
 export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.Router {
-  const { secretsVault, toolManualService, accessControl } = deps;
+  const { secretsVault, toolManualService, accessControl, connectionProbe } = deps;
   const router = express.Router();
   // A FUNCTION, not a constant. Routers are constructed at boot, and on a
   // deployment configured through the setup screen the branch model does not
@@ -361,6 +367,10 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
         value: body.value,
         label: body.label,
       });
+      // No probe here, and nothing to invalidate: a verdict is never stored, so
+      // saving a key cannot leave a stale one behind. The caller follows this
+      // with an explicit check, which keeps the save fast and gives the UI a
+      // "Testing…" state to show instead of a frozen dialog.
       res.status(201).json({ secret });
     } catch (err) {
       mapError(err, res, 'set user var');
@@ -504,6 +514,30 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     }
   });
 
+  /**
+   * Probe one tool's credential NOW and return the verdict.
+   *
+   * A POST because it has an effect on the world — it makes a real
+   * authenticated call to the provider — and because browsers and proxies are
+   * free to cache a GET, which for a freshness check would defeat the point.
+   *
+   * A probe outcome is never an HTTP error: a rejected credential is a
+   * successful check that found a problem, so it comes back 200 with
+   * `status: 'failed'`. Only a tool that can't be found or read 404s.
+   */
+  router.post('/secrets/tools/:slug/check', async (req, res) => {
+    const userId = req.userId;
+    const email = req.userEmail;
+    if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const verdict = await connectionProbe.probe(userId, email, req.params.slug);
+      if (!verdict) return void res.status(404).json({ error: 'Tool not found' });
+      res.json({ verdict });
+    } catch (err) {
+      mapError(err, res, 'check tool connection');
+    }
+  });
+
   return router;
 }
 

package/src/modules/settings/__tests__/deployment-settings.service.test.ts

@@ -150,6 +150,63 @@ describe('DeploymentSettingsService — secrets', () => {
   });
 });
 
+describe('DeploymentSettingsService — KB layout', () => {
+  it('resolves the three roots to their defaults when nothing names them', () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    expect(settings.resolveKbLayout()).toEqual({
+      knowledgeBaseDir: 'KnowledgeBase',
+      skillsDir: 'Skills',
+      pluginsDir: 'Plugins',
+    });
+  });
+
+  it('takes a renamed root from the environment first, then the store', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins' }, null);
+    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills', pluginsDir: 'plugins' });
+    process.env.KB_SKILLS_DIR = 'capabilities';
+    expect(settings.resolveKbLayout().skillsDir).toBe('capabilities');
+  });
+
+  /**
+   * The trio rule is judged on the layout the save WOULD produce: a plugins
+   * folder renamed to collide with the skills folder already in effect is a
+   * collision even though the batch names only one of them.
+   */
+  it('refuses two roots that share a name, case-insensitively', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(settings.save({ pluginsDir: 'skills' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    await expect(settings.save({ pluginsDir: 'SKILLS' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    await expect(
+      settings.save({ knowledgeBaseDir: 'Content', skillsDir: 'content' }, null),
+    ).rejects.toBeInstanceOf(SettingsValidationError);
+  });
+
+  it('refuses a root that is not a single plain folder name', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['a/b', '..', '.hidden', 'x\\y']) {
+      await expect(settings.save({ skillsDir: bad }, null)).rejects.toBeInstanceOf(
+        SettingsValidationError,
+      );
+    }
+  });
+
+  it('marks a layout change as restart-to-apply', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const { restartRequired } = await settings.save({ pluginsDir: 'Bundles' }, null);
+    expect(restartRequired).toBe(true);
+  });
+});
+
 describe('DeploymentSettingsService — validation', () => {
   it('rejects the whole batch when one field is wrong', async () => {
     const { db, rows } = makeDb();

package/src/modules/settings/__tests__/setup.routes.sync-status.test.ts

@@ -0,0 +1,77 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createSetupRoutes, type LastSyncStatus } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * The remote-sync facts on `GET /setup/status`: the address a hook calls and
+ * what the last sync did. Admin-only like the rest of the settings — a
+ * non-admin learns nothing about the deployment's endpoints.
+ */
+const ENC_KEY = randomBytes(32).toString('base64');
+
+let server: HttpServer | null = null;
+afterEach(() => {
+  server?.close();
+  server = null;
+});
+
+function listen(isAdmin: boolean, last: LastSyncStatus | null) {
+  const db = {
+    select: () => ({ from: () => Promise.resolve([]) }),
+    insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  const settings = new DeploymentSettingsService(db, ENC_KEY);
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userEmail = 'root@example.com';
+    req.userId = 'user-1';
+    next();
+  });
+  app.use(
+    '/api',
+    createSetupRoutes(
+      settings,
+      { isAdmin: async () => isAdmin } as IAdminAccessService,
+      { runAll: async () => {} },
+      { url: 'https://hexis.example.test/api/sync', lastSync: () => last },
+    ),
+  );
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+describe('GET /setup/status — remote sync', () => {
+  it('tells an admin the address and the last sync', async () => {
+    const last: LastSyncStatus = {
+      at: 1_700_000_000_000,
+      by: 'bearer',
+      status: 'synced',
+      results: [{ branch: 'main', outcome: 'updated' }],
+    };
+    const res = await fetch(`${listen(true, last)}/api/setup/status`);
+    const body = (await res.json()) as { sync?: unknown };
+    expect(body.sync).toEqual({ url: 'https://hexis.example.test/api/sync', last });
+  });
+
+  it('says null before the first sync', async () => {
+    const res = await fetch(`${listen(true, null)}/api/setup/status`);
+    const body = (await res.json()) as { sync?: { last: unknown } };
+    expect(body.sync?.last).toBeNull();
+  });
+
+  it('tells a non-admin nothing', async () => {
+    const res = await fetch(`${listen(false, null)}/api/setup/status`);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.sync).toBeUndefined();
+    expect(body.settings).toBeUndefined();
+  });
+});

package/src/modules/settings/deployment-settings.service.ts

@@ -1,7 +1,12 @@
 import { eq, inArray } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { deploymentSettings } from '../database/core-schema.js';
-import { validateBranchModel } from '@bevel-software/platform-shared';
+import {
+  DEFAULT_KB_LAYOUT,
+  validateBranchModel,
+  validateKbLayout,
+  validateKbRootName,
+} from '@bevel-software/platform-shared';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 
 /**
@@ -85,6 +90,38 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
   },
 
+  /**
+   * The KB layout: the three root folders a deployment may rename so hexis can
+   * read a repository laid out by someone else (`skills/` and `plugins/` in
+   * lowercase, say). Restart-to-apply like the branch model — the names are
+   * applied once at boot through `configureKbLayout` and served to the browser
+   * once by `/api/config`. Each has a default, so an unset field means the
+   * default, not an unconfigured deployment. Checked as a trio in `save`: the
+   * three must differ, and one field alone cannot see the other two.
+   */
+  {
+    key: 'knowledgeBaseDir',
+    envVar: 'KB_KNOWLEDGE_BASE_DIR',
+    section: 'knowledge-base',
+    validate: validateKbRootName,
+    restartToApply: true,
+  },
+  {
+    key: 'skillsDir',
+    envVar: 'KB_SKILLS_DIR',
+    section: 'knowledge-base',
+    validate: validateKbRootName,
+    restartToApply: true,
+  },
+  {
+    key: 'pluginsDir',
+    envVar: 'KB_PLUGINS_DIR',
+    section: 'knowledge-base',
+    validate: validateKbRootName,
+    restartToApply: true,
+  },
+
+
   /**
    * The branch model. Both are restart-to-apply and could not be otherwise:
    * the backend hands `DEFAULT_BRANCH` to services at construction, and the
@@ -109,6 +146,25 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
   },
 
+  {
+    /**
+     * The credential a git host's webhook or a pipeline presents to
+     * `POST /api/sync` (see `modules/kb-sync/`). Deployment-level on purpose:
+     * a person's connection key would stop the pipeline the day they leave.
+     * Optional — without it the endpoint only admits an admin's own session.
+     * Read per request, so it applies without a restart.
+     */
+    key: 'kbSyncSecret',
+    envVar: 'KB_SYNC_SECRET',
+    section: 'knowledge-base',
+    secret: true,
+    // The same floor `sync-auth.ts` enforces at request time (which is what
+    // covers a secret set through the environment); this one just says so
+    // before the save.
+    validate: (v) =>
+      v.trim().length >= 16 ? null : 'Use at least 16 characters — a random string is best.',
+  },
+
   /**
    * Single sign-on. Restart-to-apply because the provider is built once at boot
    * and pushed into the auth plugin array the server mounts from.
@@ -266,6 +322,18 @@ export class DeploymentSettingsService {
     return (this.stored.get(key) ?? '').trim();
   }
 
+  /**
+   * The KB layout in effect: each root from the environment, else the stored
+   * row, else its default. The composition root applies this once at boot.
+   */
+  resolveKbLayout(): { knowledgeBaseDir: string; skillsDir: string; pluginsDir: string } {
+    return {
+      knowledgeBaseDir: this.resolve('knowledgeBaseDir') || DEFAULT_KB_LAYOUT.knowledgeBaseDir,
+      skillsDir: this.resolve('skillsDir') || DEFAULT_KB_LAYOUT.skillsDir,
+      pluginsDir: this.resolve('pluginsDir') || DEFAULT_KB_LAYOUT.pluginsDir,
+    };
+  }
+
   /** Where {@link resolve} got its answer — what the setup screen labels the field with. */
   sourceOf(key: string): SettingSource {
     const def = this.defs.get(key);
@@ -356,11 +424,36 @@ export class DeploymentSettingsService {
       if (problem) problems.protectedBranches = problem;
     }
 
+    // The layout trio is the other cross-field rule: three names that must
+    // differ. Judged on the layout this save WOULD produce, with the default
+    // standing in for anything neither written nor stored.
+    const layoutKeys = ['knowledgeBaseDir', 'skillsDir', 'pluginsDir'] as const;
+    if (toWrite.some((w) => (layoutKeys as readonly string[]).includes(w.key))) {
+      const effective = (key: (typeof layoutKeys)[number]) =>
+        toWrite.find((w) => w.key === key)?.value || this.resolve(key) || DEFAULT_KB_LAYOUT[key];
+      const problem = validateKbLayout({
+        knowledgeBaseDir: effective('knowledgeBaseDir'),
+        skillsDir: effective('skillsDir'),
+        pluginsDir: effective('pluginsDir'),
+      });
+      // Against the field being written — the first one in the batch — since
+      // any of the three could be the one that collides.
+      if (problem) {
+        const first = toWrite.find((w) => (layoutKeys as readonly string[]).includes(w.key))!;
+        problems[first.key] = problem;
+      }
+    }
+
     if (Object.keys(problems).length > 0) throw new SettingsValidationError(problems);
 
     let restartRequired = false;
     for (const { key, value, def } of toWrite) {
-      if (def.restartToApply && this.resolve(key) !== value) restartRequired = true;
+      // Compared against the EFFECTIVE value: a layout root that was unset
+      // was already running on its default, so saving that default changes
+      // nothing a restart would pick up.
+      const effective =
+        this.resolve(key) || (DEFAULT_KB_LAYOUT as Record<string, string | undefined>)[key] || '';
+      if (def.restartToApply && effective !== value) restartRequired = true;
       const encrypted = def.secret === true;
       const stored = encrypted ? this.crypto!.encrypt(value) : value;
       await this.db

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

@@ -16,6 +16,18 @@ import '../auth/auth.middleware.js'; // Express Request augmentation
 
 const execFileAsync = promisify(execFile);
 
+/**
+ * The slice of a sync record the status endpoint publishes. Declared here
+ * rather than imported from `kb-sync` so this module stays free of that one;
+ * the composition root hands in something that satisfies it.
+ */
+export interface LastSyncStatus {
+  at: number;
+  by: string;
+  status: 'synced' | 'partial';
+  results: Array<{ branch: string; outcome: string; error?: string }>;
+}
+
 /**
  * First-run setup — the deployment's own configuration, for the things that
  * used to be environment-only.
@@ -37,6 +49,17 @@ export function createSetupRoutes(
    * would race.
    */
   kbStartupRunner: { runAll(): Promise<void> },
+  /**
+   * 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.
+   * Optional so a minimal mount (tests, a distribution without the module)
+   * simply omits them from the status.
+   */
+  sync?: {
+    /** `<PUBLIC_BACKEND_URL>/api/sync` — the reader appends `/<branch>`. */
+    url: string;
+    lastSync(): LastSyncStatus | null;
+  },
 ): express.Router {
   const router = express.Router();
 
@@ -101,6 +124,7 @@ export function createSetupRoutes(
       isAdmin: true,
       settings: settings.describe(),
       ...(kbInitFailed ? { kbInitError } : {}),
+      ...(sync ? { sync: { url: sync.url, last: sync.lastSync() } } : {}),
     });
   });
 

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

@@ -0,0 +1,128 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+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';
+
+/**
+ * The branch probe behind an access request: the listing is used to PROVE a
+ * branch absent before one is cut, so it must be the strict kind — a stale
+ * list (a fetch that failed) proves nothing, and the route must stop rather
+ * than write a proposal onto a branch it never confirmed.
+ */
+
+const KB = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+const MIA = { id: 'u-mia', email: 'mia@x.io', name: 'Mia' };
+const FOLDER = 'Skills/Eng/deploy';
+
+async function makeHarness(listBranches: IWorkflowService['listBranches']) {
+  const workflow = {
+    listChangeRequestsAuthoredBy: vi.fn(async () => []),
+    listBranches: vi.fn(listBranches),
+    createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
+    commitChanges: vi.fn(async () => null),
+    openChangeRequest: vi.fn(async () => ({ number: 42 })),
+  } 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'),
+    writeFile: vi.fn(async () => undefined),
+  } as unknown as WorkspaceService;
+  const accessControl = { canWrite: vi.fn(async () => false) } as unknown as IAccessControl;
+  const skillService = {
+    listSkills: vi.fn(async () => [{ name: 'deploy', description: '', path: FOLDER }]),
+  } as unknown as ISkillService;
+
+  const app = express();
+  app.use(express.json());
+  app.use(
+    '/api',
+    createSkillAccessRequestRoutes({
+      skillService,
+      accessControl,
+      workflow,
+      workspaceService,
+      joinRequests: { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService,
+      kbDirName: KB,
+      resolveUser: async () => MIA,
+    }),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const { port } = server.address() as AddressInfo;
+  return { server, url: `http://127.0.0.1:${port}/api/skills/deploy/access-request`, workflow, workspaceService };
+}
+
+describe('POST /skills/:name/access-request — the branch probe', () => {
+  let server: Server | null = null;
+  afterEach(async () => {
+    // Released here, not after the assertions: a failing assertion must not
+    // leave the console muted for every test that follows.
+    vi.restoreAllMocks();
+    if (server) await new Promise<void>((r) => server!.close(() => r()));
+    server = null;
+  });
+
+  it('proves absence with a STRICT fresh listing, then cuts the branch and opens the request', async () => {
+    const h = await makeHarness(async () => []);
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, number: 42 });
+    expect(h.workflow.listBranches).toHaveBeenCalledWith(wsId, { freshFetch: true, strictFetch: true });
+    expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, joinBranchFor(MIA.email, FOLDER), DEFAULT_BRANCH);
+    // The whole chain the probe exists to enable: the grant is written AND committed.
+    expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
+    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+  });
+
+  it('a create that loses the race proceeds once the fresh re-probe shows the branch', async () => {
+    const branch = joinBranchFor(MIA.email, FOLDER);
+    // Absent on the first probe, present on the second: someone else cut it in between.
+    let probes = 0;
+    const h = await makeHarness(async () => (probes++ === 0 ? [] : [{ name: branch, isDefault: false, isProtected: false }]));
+    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('already exists'));
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, number: 42 });
+    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
+    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+  });
+
+  it('a create that fails with no branch to show for it stops the request — nothing is written on a branch that was not made', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const h = await makeHarness(async () => []);
+    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('origin refused'));
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(500);
+    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
+    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('a listing that could not prove anything stops the request before a branch or a byte is written', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const h = await makeHarness(async () => {
+      throw new Error('the fetch from origin failed, so the branch list cannot prove absence');
+    });
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(500);
+    expect(h.workflow.createBranch).not.toHaveBeenCalled();
+    expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
+    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+  });
+});

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

@@ -67,6 +67,62 @@ describe('SkillService', () => {
   });
   afterEach(() => rm(root, { recursive: true, force: true }));
 
+  test('lists shared skills under the Skills root alongside plugin skills', async () => {
+    const shared = join(root, wsId, KB_DIR, 'Skills', 'Engineering', 'deploy');
+    await mkdir(shared, { recursive: true });
+    await writeFile(join(shared, 'SKILL.md'), '---\ndescription: Ship it.\n---\n\n# Deploy\n');
+    // A skill directly under the root, no scope folder — also a skill.
+    const bare = join(root, wsId, KB_DIR, 'Skills', 'triage');
+    await mkdir(bare, { recursive: true });
+    await writeFile(join(bare, 'SKILL.md'), '---\ndescription: Triage.\n---\n');
+
+    const list = await svc().listSkills();
+    expect(list.find((s) => s.name === 'deploy')?.path).toBe('Skills/Engineering/deploy');
+    expect(list.find((s) => s.name === 'triage')?.path).toBe('Skills/triage');
+    // The plugin tree is still scanned: the union is the catalog.
+    expect(list.find((s) => s.name === 'rfi')?.path).toBe('Plugins/rfi');
+
+    const res = await svc().getSkill('u@x.io', 'deploy');
+    expect(res.ok && res.kind === 'skill' && res.skill.body).toContain('# Deploy');
+  });
+
+  test('honours a .bevelignore inside a root, so a build output never shadows the source', async () => {
+    // A repository that commits a compiled copy of every skill beside the
+    // source: without the ignore, `dist/…/rfi` would collide with `Plugins/rfi`.
+    const dist = join(root, wsId, KB_DIR, 'Skills', 'dist', 'rfi');
+    await mkdir(dist, { recursive: true });
+    await writeFile(join(dist, 'SKILL.md'), '---\ndescription: compiled copy\n---\n');
+    await writeFile(join(root, wsId, KB_DIR, 'Skills', '.bevelignore'), 'dist/\n');
+
+    const list = await svc().listSkills();
+    expect(list.filter((s) => s.name === 'rfi').map((s) => s.path)).toEqual(['Plugins/rfi']);
+    expect(list.some((s) => s.path.includes('/dist/'))).toBe(false);
+  });
+
+  test('ignores the repo-root .bevelignore: hiding a root from the file tree must not empty the catalog', async () => {
+    // The seeded template hides `Plugins/` (and `Skills/`) from the Knowledge
+    // tree with exactly this file. The catalog is what those roots exist for.
+    await writeFile(join(root, wsId, KB_DIR, '.bevelignore'), 'Plugins/\nSkills/\n');
+    const shared = join(root, wsId, KB_DIR, 'Skills', 'deploy');
+    await mkdir(shared, { recursive: true });
+    await writeFile(join(shared, 'SKILL.md'), '---\ndescription: Ship it.\n---\n');
+
+    const list = await svc().listSkills();
+    expect(list.map((s) => s.name).sort()).toEqual(['coding-guidelines', 'deploy', 'rfi']);
+  });
+
+  test('a nested .bevelignore applies beneath the folder that carries it', async () => {
+    const scope = join(root, wsId, KB_DIR, 'Skills', 'Sales');
+    await mkdir(join(scope, 'drafts', 'pitch'), { recursive: true });
+    await mkdir(join(scope, 'pitch'), { recursive: true });
+    await writeFile(join(scope, 'drafts', 'pitch', 'SKILL.md'), '---\ndescription: draft\n---\n');
+    await writeFile(join(scope, 'pitch', 'SKILL.md'), '---\ndescription: released\n---\n');
+    await writeFile(join(scope, '.bevelignore'), 'drafts/\n');
+
+    const list = await svc().listSkills();
+    expect(list.filter((s) => s.name === 'pitch').map((s) => s.path)).toEqual(['Skills/Sales/pitch']);
+  });
+
   test('lists skills with a block-scalar description parsed correctly', async () => {
     const skills = await svc().listSkills();
     expect(skills).toHaveLength(2);
@@ -145,6 +201,35 @@ describe('SkillService', () => {
     expect(trav).toEqual({ ok: false, error: 'invalid_file' });
   });
 
+  test('an ignored SKILL.md suppresses the skill and NEVER promotes its assets to skills', async () => {
+    const rfi = join(root, wsId, KB_DIR, 'Plugins', 'rfi');
+    await writeFile(join(rfi, '.bevelignore'), 'SKILL.md\n');
+    await mkdir(join(rfi, 'examples'), { recursive: true });
+    await writeFile(join(rfi, 'examples', 'SKILL.md'), '---\ndescription: An example, not a skill.\n---\n');
+    const names = (await svc().listSkills()).map((s) => s.name);
+    expect(names).not.toContain('rfi');
+    expect(names).not.toContain('examples');
+  });
+
+  test('ignore rules reach a skill\'s bundled files: hidden from the listing and refused when asked for', async () => {
+    const rfi = join(root, wsId, KB_DIR, 'Plugins', 'rfi');
+    await writeFile(join(rfi, '.bevelignore'), 'scripts/\n');
+    const res = await svc().getSkill('user@x.eu', 'rfi');
+    expect(res.ok && res.kind === 'skill' ? res.skill.files : null).toEqual([]);
+    expect(await svc().getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py')).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+  });
+
+  test('a skill that exists inline AND under the shared root resolves to the shared copy', async () => {
+    const shared = join(root, wsId, KB_DIR, 'Skills', 'Ops', 'rfi');
+    await mkdir(shared, { recursive: true });
+    await writeFile(join(shared, 'SKILL.md'), '---\ndescription: The canonical one.\n---\n');
+    const rfi = (await svc().listSkills()).find((s) => s.name === 'rfi');
+    expect(rfi?.path).toBe('Skills/Ops/rfi');
+  });
+
   test('listSkills filters by canRead for a given user', async () => {
     const denyRfi: IAccessControl = {
       canRead: async () => false,

package/src/modules/skills/index.ts

@@ -2,6 +2,7 @@ export { SkillService } from './skills.service.js';
 export { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
+export { createSkillAccessRequestRoutes } from './skill-access-requests.routes.js';
 export type {
   ISkillService,
   IPendingSkillService,

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

@@ -1,6 +1,7 @@
 import {
   DEFAULT_BRANCH,
   PLUGINS_DIR,
+  SKILLS_DIR,
   type ChangeRequest,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
@@ -118,6 +119,8 @@ export class PendingSkillsService implements IPendingSkillService {
         name: isSafeSkillName(declared) ? declared : folderName,
         description: fm.description,
         version: fm.version,
+        owner: fm.owner,
+        lifecycle: fm.lifecycle,
         path: folder,
         changeRequestNumber: cr.number,
         branch: cr.branch,
@@ -156,11 +159,10 @@ export class PendingSkillsService implements IPendingSkillService {
  */
 function isSkillDoc(repoRelPath: string): boolean {
   const segments = repoRelPath.split('/');
-  return (
-    segments.length >= 4 &&
-    segments[0] === PLUGINS_DIR &&
-    segments[segments.length - 1] === SKILL_DOC
-  );
+  if (segments[segments.length - 1] !== SKILL_DOC) return false;
+  // Under `Skills/` a skill may sit directly below the root: `Skills/<skill>/SKILL.md`.
+  if (segments[0] === SKILLS_DIR) return segments.length >= 3;
+  return segments.length >= 4 && segments[0] === PLUGINS_DIR;
 }
 
 /** The skill folder holding a SKILL.md. */