@bevel-software/platform-core-backend 0.4.0 → 0.5.0

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

@@ -0,0 +1,317 @@
+import express from 'express';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import {
+  DeploymentSettingsService,
+  SettingsValidationError,
+  validateHttpsRemote,
+} from './deployment-settings.service.js';
+import {
+  configureBranchModel,
+  isBranchModelConfigured,
+  validateBranchModel,
+} from '@bevel-software/platform-shared';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * First-run setup — the deployment's own configuration, for the things that
+ * used to be environment-only.
+ *
+ * WHY THESE ROUTES ARE AUTHENTICATED BUT NOT KB-DEPENDENT: the whole point is
+ * to be reachable on a deployment that has no knowledge base yet. That works
+ * because the bootstrap admin (`ADMIN_EMAIL`) is recognised without consulting
+ * `roles.yaml` — `AdminAccessService` short-circuits on it before any clone is
+ * attempted — so the one person who can finish setup can always sign in, and
+ * nobody else is let near it.
+ */
+export function createSetupRoutes(
+  settings: DeploymentSettingsService,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  const requireAdmin: express.RequestHandler = async (req, res, next) => {
+    if (!(await adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    next();
+  };
+
+  /**
+   * Whether the deployment is usable, and — for an admin — what is missing.
+   *
+   * Deliberately readable by ANY signed-in user, because everyone needs the
+   * answer: a non-admin who arrives mid-setup gets told the deployment is
+   * still being configured instead of a broken file tree. Only the admin
+   * branch carries the settings themselves, and no branch ever carries a
+   * secret's value.
+   */
+  router.get('/setup/status', async (req, res) => {
+    const complete = isComplete(settings);
+    if (!(await adminAccess.isAdmin(req.userEmail))) {
+      res.json({ complete, isAdmin: false });
+      return;
+    }
+    res.json({
+      complete,
+      awaitingRestart: awaitingRestart(settings),
+      isAdmin: true,
+      settings: settings.describe(),
+    });
+  });
+
+  /**
+   * Save settings. Validated and written as ONE batch — a repository URL
+   * stored without the token that reads it is a deployment that fails at its
+   * first clone, so a partial write is never better than none.
+   */
+  router.post('/setup/settings', requireAdmin, async (req, res) => {
+    const body = (req.body ?? {}) as { settings?: Record<string, unknown> };
+    const entries: Record<string, string> = {};
+    for (const [key, value] of Object.entries(body.settings ?? {})) {
+      if (typeof value !== 'string') {
+        res.status(400).json({ error: `"${key}" must be a string.` });
+        return;
+      }
+      entries[key] = value;
+    }
+    try {
+      const { restartRequired } = await settings.save(entries, req.userId ?? null);
+      /**
+       * Apply the branch model to THIS process, so pressing Save finishes
+       * setup instead of asking for a restart.
+       *
+       * Only when it was not already configured — reconfiguring a live
+       * deployment mid-flight would swap the branches out from under sessions
+       * that are using them, which is a different and much less welcome
+       * feature. Going from "none" to "some" has nobody to disturb: the app is
+       * gated shut until exactly this moment.
+       *
+       * The services that need it read it when they use it rather than
+       * capturing it at construction, which is what makes applying it here
+       * enough.
+       */
+      if (!isBranchModelConfigured()) {
+        const model = {
+          defaultBranch: settings.resolve('defaultBranch'),
+          protectedBranches: settings.resolve('protectedBranches'),
+        };
+        if (!validateBranchModel(model)) configureBranchModel(model);
+      }
+      res.json({
+        ok: true,
+        restartRequired,
+        complete: isComplete(settings),
+        awaitingRestart: awaitingRestart(settings),
+        settings: settings.describe(),
+      });
+    } catch (err) {
+      if (err instanceof SettingsValidationError) {
+        res.status(400).json({ error: 'Some settings need fixing.', problems: err.problems });
+        return;
+      }
+      // Logged in full, returned generic: a driver message here would hand back
+      // the schema or the connection string.
+      console.error('[setup] save failed:', err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: 'Could not save these settings.' });
+    }
+  });
+
+  /**
+   * Try the credentials against the real remote, BEFORE anything is saved.
+   *
+   * This is the reason the screen is worth more than the environment variables
+   * it replaces. `ls-remote` is the cheapest operation that proves all three
+   * values at once — the URL resolves, the token authenticates, and the
+   * username is the one this host expects — and it answers in a second instead
+   * of surfacing as a failed clone at some later, unrelated moment.
+   *
+   * Values are taken from the request when supplied so an admin can test what
+   * they typed rather than what is stored, and fall back to what is in effect
+   * (which is how "test the token I saved last week" works).
+   */
+  router.post('/setup/test-connection', requireAdmin, async (req, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const supplied = (key: string): string | null => {
+      const value = body[key];
+      return typeof value === 'string' && value.trim() ? value.trim() : null;
+    };
+    const url = supplied('kbRepoUrl') ?? settings.resolve('kbRepoUrl');
+    // Unlike the token, the username is not a secret and carries a default —
+    // it is which name the host expects beside the token, not a credential.
+    const username =
+      supplied('gitUsername') ?? (settings.resolve('gitUsername') || 'x-access-token');
+
+    if (!url) {
+      res.status(400).json({ ok: false, error: 'Enter the repository URL first.' });
+      return;
+    }
+
+    /**
+     * THE CONFIGURED TOKEN ONLY EVER GOES TO THE CONFIGURED REPOSITORY.
+     *
+     * The stored token is deliberately unreadable — `describe()` omits it, so
+     * an admin can replace it but never see it. Falling back to it for whatever
+     * URL the request names would hand that value straight back: point the test
+     * at a host you control, read it out of the request. Admin-gated, but the
+     * whole point of not returning it is that being an admin is not the same as
+     * being allowed to hold it.
+     *
+     * So a request that names a DIFFERENT repository has to bring its own
+     * credential. Testing what is already configured — the "does the token I
+     * saved last week still work?" case — is unaffected.
+     */
+    const suppliedToken = supplied('gitToken');
+    const testingConfiguredRepo = url === settings.resolve('kbRepoUrl');
+    if (!suppliedToken && !testingConfiguredRepo) {
+      res.status(400).json({
+        ok: false,
+        error: 'Enter the access token for that repository — the saved one is only used with the repository it was saved for.',
+      });
+      return;
+    }
+    const token = suppliedToken ?? (testingConfiguredRepo ? settings.resolve('gitToken') : '');
+    // The SAME rule the setting is validated by, applied before the value ever
+    // reaches git. Without it this endpoint is argument injection: a value
+    // beginning `--upload-pack=` makes git run a command of the caller's
+    // choosing, and `ext::sh -c …` is a transport whose entire purpose is to
+    // execute one. Both are admin-only, but "admin" is not "may run arbitrary
+    // commands as the server process".
+    const urlProblem = validateHttpsRemote(url);
+    if (urlProblem) {
+      res.status(400).json({ ok: false, error: urlProblem });
+      return;
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(username)) {
+      // Interpolated into the credential-helper snippet below.
+      res.status(400).json({ ok: false, error: 'The username contains unsupported characters.' });
+      return;
+    }
+
+    try {
+      // The helper reads the token from the environment at call time, so it
+      // never appears in argv (and so never in a process listing or a crash
+      // dump). Same shape the real clone uses.
+      const args = ['-c', 'credential.helper=', ...(token
+        ? ['-c', `credential.helper=!f() { echo "username=${username}"; echo "password=$BEVEL_TEST_TOKEN"; }; f`]
+        : []),
+        // `--end-of-options` on top of the validation above: belt and braces,
+        // so nothing that arrives here can ever be read as a flag.
+        'ls-remote', '--heads', '--end-of-options', url];
+      const { stdout } = await execFileAsync('git', args, {
+        timeout: 20_000,
+        env: {
+          ...process.env,
+          BEVEL_TEST_TOKEN: token,
+          // Never let git stop for a prompt: without this a bad credential
+          // hangs the request until the timeout instead of failing.
+          GIT_TERMINAL_PROMPT: '0',
+          GIT_ASKPASS: 'echo',
+        },
+      });
+      const lines = stdout.split('\n');
+      // `<sha>\trefs/heads/<name>` — tag refs and the bare HEAD row are not
+      // branches, so they are filtered rather than sliced blindly.
+      const branches = lines
+        .filter((line) => !line.startsWith('ref:'))
+        .map((line) => line.split('\t')[1]?.trim())
+        .filter((ref): ref is string => !!ref && ref.startsWith('refs/heads/'))
+        .map((ref) => ref.slice('refs/heads/'.length));
+      // `ref: refs/heads/<name>\tHEAD` — what the remote calls its own trunk.
+      const defaultBranch =
+        lines
+          .find((line) => line.startsWith('ref:') && line.trimEnd().endsWith('HEAD'))
+          ?.slice('ref: refs/heads/'.length)
+          .split('\t')[0]
+          ?.trim() || null;
+      res.json({
+        ok: true,
+        // An EMPTY repository is a success, not a failure — seeding one is a
+        // supported path, and saying "no branches yet" beats an error that
+        // reads like the credentials are wrong.
+        empty: branches.length === 0,
+        branches,
+        defaultBranch,
+      });
+    } catch (err) {
+      res.status(200).json({ ok: false, error: explainGitFailure(err, token) });
+    }
+  });
+
+  return router;
+}
+
+/**
+ * Whether the STORED configuration answers everything the deployment needs.
+ *
+ * The KB needs a URL and a token — the username and the directory name both
+ * have working defaults, so neither can block a start. The branch model has no
+ * default ON PURPOSE: guessing `main` would silently point a deployment at the
+ * wrong branch and let the protected-branch guards apply to nothing, which is
+ * worse than asking.
+ *
+ * SSO is deliberately absent. It is configuration, not a prerequisite — a
+ * 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'));
+  const branches =
+    validateBranchModel({
+      defaultBranch: settings.resolve('defaultBranch'),
+      protectedBranches: settings.resolve('protectedBranches'),
+    }) === null;
+  return kb && branches;
+}
+
+/**
+ * Whether THIS PROCESS can actually serve — which is not the same question,
+ * and conflating them opened the gate onto a broken app.
+ *
+ * The branch model is applied once, during boot: services take `DEFAULT_BRANCH`
+ * at construction and the browser is served it before it renders. Saving it
+ * therefore answers the question without changing the answer this process
+ * holds — so a deployment configured through the setup screen reported itself
+ * complete while every workspace call still failed with
+ * `Invalid branch name ""`.
+ *
+ * Requiring the model to be IN EFFECT keeps the gate shut until the restart
+ * 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();
+}
+
+/** Answered, but not yet in effect: everything is stored, the process is stale. */
+export function awaitingRestart(settings: DeploymentSettingsService): boolean {
+  return settingsAnswered(settings) && !isBranchModelConfigured();
+}
+
+/**
+ * Turn git's stderr into something an admin can act on. Deliberately narrow:
+ * the raw text is echoed only when it matches nothing known, and the token is
+ * scrubbed from it first — `ls-remote` failures have been known to quote the
+ * credential back.
+ */
+function explainGitFailure(err: unknown, token: string): string {
+  const raw = err instanceof Error ? `${err.message}` : String(err);
+  const text = token ? raw.replaceAll(token, '***') : raw;
+  if (/timed out|ETIMEDOUT/i.test(text)) {
+    return 'The host did not answer in time. Check the URL, and that this server can reach it.';
+  }
+  if (/Authentication failed|could not read Username|invalid credentials|403/i.test(text)) {
+    return 'The host rejected those credentials. Check the token, and that the username matches the host (GitHub x-access-token, GitLab oauth2, Bitbucket x-token-auth).';
+  }
+  if (/not found|repository .* does not exist|404/i.test(text)) {
+    return 'No repository at that URL — or the token cannot see it.';
+  }
+  if (/could not resolve host|unable to access|SSL|certificate/i.test(text)) {
+    return 'Could not reach that host from this server. Check the URL and any network egress rules.';
+  }
+  return text.split('\n').slice(0, 3).join(' ').slice(0, 400);
+}

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

@@ -0,0 +1,240 @@
+import { describe, test, expect } from 'vitest';
+import type { ChangeRequest, IWorkflowService } from '@bevel-software/platform-shared';
+import { PendingSkillsService } from '../pending-skills.service.js';
+import { hashEmail } from '../../../shared/hash-email.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';
+
+/**
+ * The half of the catalog that is NOT on the default branch.
+ *
+ * The bug this exists for: an agent opened a change request adding a skill, and
+ * the skill was nowhere in the product until somebody merged it — not for the
+ * author, not for the person who had to approve it. So the tests below are
+ * mostly about who gets to see one, because "show it" and "show it to the wrong
+ * people" are the two ways to get this wrong.
+ */
+
+const AUTHOR = 'ali@bevel.software';
+const ADMIN = 'olga@bevel.software';
+const BYSTANDER = 'sam@bevel.software';
+
+const SKILL_MD = `---
+name: weekly-newsletter
+version: 0.1.0
+description: Drafts the Friday newsletter.
+---
+
+# Weekly newsletter
+`;
+
+function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
+  return {
+    number: 7,
+    title: 'Add the weekly-newsletter skill',
+    authorId: hashEmail(AUTHOR),
+    author: { login: 'user-abc', name: 'service' },
+    appAuthor: { name: 'Ali Raza' },
+    branch: 'agent/weekly-newsletter',
+    base: 'main',
+    state: 'open',
+    createdAt: '2026-08-06T09:00:00.000Z',
+    touchedNodePaths: ['Groups/Engineering/weekly-newsletter/SKILL.md'],
+    review: { approvals: 0, changesRequested: 0, pendingLogins: [] },
+    url: '/change-requests/7',
+    ...over,
+  };
+}
+
+/** Files present on a change request's branch, keyed `<branch>:<path>`. */
+function harness(opts: {
+  crs: ChangeRequest[];
+  released?: SkillSummary[];
+  branchFiles?: Record<string, string>;
+  /** Emails allowed to write each path. Absent path ⇒ nobody. */
+  writers?: Record<string, string[]>;
+}) {
+  const branchFiles = opts.branchFiles ?? {
+    'agent/weekly-newsletter:Groups/Engineering/weekly-newsletter/SKILL.md': SKILL_MD,
+  };
+  const workspaceService = {
+    ensureRemotesFetched: async () => undefined,
+    readFileAtRef: async (_ws: string, ref: string, rel: string) =>
+      branchFiles[`${ref.replace(/^origin\//, '')}:${rel}`] ?? null,
+  } as unknown as WorkspaceService;
+
+  const accessControl = {
+    canWriteBatch: async (_ws: string, email: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, (opts.writers?.[p] ?? []).includes(email)])),
+  } as unknown as IAccessControl;
+
+  const skillService = {
+    listSkills: async () => opts.released ?? [],
+  } as unknown as ISkillService;
+
+  const workflow = {
+    listChangeRequests: async () => opts.crs,
+  } as unknown as IWorkflowService;
+
+  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow);
+}
+
+const ADMIN_WRITES = {
+  'Groups/Engineering/weekly-newsletter/SKILL.md': [ADMIN],
+};
+
+describe('PendingSkillsService', () => {
+  test('surfaces a skill that exists only on a change request, to its author', async () => {
+    const pending = await harness({ crs: [cr()], writers: ADMIN_WRITES }).listPendingSkills(AUTHOR);
+
+    expect(pending).toEqual([
+      {
+        name: 'weekly-newsletter',
+        description: 'Drafts the Friday newsletter.',
+        version: '0.1.0',
+        path: 'Groups/Engineering/weekly-newsletter',
+        changeRequestNumber: 7,
+        branch: 'agent/weekly-newsletter',
+        authorName: 'Ali Raza',
+        createdAt: '2026-08-06T09:00:00.000Z',
+        isAuthor: true,
+      },
+    ]);
+  });
+
+  test('surfaces it to whoever could approve it, marked as not theirs', async () => {
+    const pending = await harness({ crs: [cr()], writers: ADMIN_WRITES }).listPendingSkills(ADMIN);
+    expect(pending.map((p) => [p.name, p.isAuthor])).toEqual([['weekly-newsletter', false]]);
+  });
+
+  /**
+   * The decision that shapes this surface: a proposal is between its author and
+   * the people who can approve it, and nobody else. A member of the group who
+   * cannot write the folder is not one of those people.
+   */
+  test('hides it from everyone else', async () => {
+    expect(await harness({ crs: [cr()], writers: ADMIN_WRITES }).listPendingSkills(BYSTANDER))
+      .toEqual([]);
+  });
+
+  /**
+   * Fail closed like the catalog: an access lookup that cannot answer is a
+   * denial, never a disclosure. Without this a broken access tree would show
+   * every open proposal to everyone.
+   */
+  test('shows nothing to a non-author when the access tree cannot be read', async () => {
+    // No writer on any path is what an unreadable tree looks like from here.
+    const broken = harness({ crs: [cr()], writers: {} });
+    expect(await broken.listPendingSkills(ADMIN)).toEqual([]);
+    // …and the author still sees their own, because that verdict needs no tree.
+    expect(await broken.listPendingSkills(AUTHOR)).toHaveLength(1);
+  });
+
+  /**
+   * A change request that EDITS a released skill is not a pending skill — the
+   * skill page already carries those, and duplicating them here would put a
+   * second, ghost card beside every skill under review.
+   */
+  test('ignores a change request against a skill that is already released', async () => {
+    const svc = harness({
+      crs: [cr()],
+      released: [
+        {
+          name: 'weekly-newsletter',
+          description: 'Drafts the Friday newsletter.',
+          path: 'Groups/Engineering/weekly-newsletter',
+        },
+      ],
+      writers: ADMIN_WRITES,
+    });
+    expect(await svc.listPendingSkills(AUTHOR)).toEqual([]);
+  });
+
+  test('ignores touched paths that are not a skill of their own', async () => {
+    const svc = harness({
+      crs: [
+        cr({
+          touchedNodePaths: [
+            'Groups/Engineering/access.md',
+            'Groups/Engineering/SKILL.md', // a group folder is not a skill
+            'Groups/Engineering/weekly-newsletter/reference.md',
+          ],
+        }),
+      ],
+      writers: ADMIN_WRITES,
+    });
+    expect(await svc.listPendingSkills(AUTHOR)).toEqual([]);
+  });
+
+  /**
+   * The proposal is read at the request's own branch. Reading the default
+   * branch would find nothing and drop the card — which is the original bug.
+   */
+  test('drops a proposal whose SKILL.md cannot be read on its branch', async () => {
+    const svc = harness({ crs: [cr()], branchFiles: {}, writers: ADMIN_WRITES });
+    expect(await svc.listPendingSkills(AUTHOR)).toEqual([]);
+  });
+
+  test('ignores change requests that are not open', async () => {
+    const svc = harness({ crs: [cr({ state: 'merged' })], writers: ADMIN_WRITES });
+    expect(await svc.listPendingSkills(AUTHOR)).toEqual([]);
+  });
+
+  test('falls back to the folder name when the frontmatter declares no id', async () => {
+    const svc = harness({
+      crs: [cr()],
+      branchFiles: {
+        'agent/weekly-newsletter:Groups/Engineering/weekly-newsletter/SKILL.md':
+          '---\ndescription: No name declared.\n---\n\n# Body\n',
+      },
+      writers: ADMIN_WRITES,
+    });
+    const [pending] = await svc.listPendingSkills(AUTHOR);
+    expect(pending.name).toBe('weekly-newsletter');
+    expect(pending.version).toBeUndefined();
+  });
+
+  /**
+   * This hangs off the library's list load. A workflow service that cannot
+   * answer must cost the reader an empty review shelf, not their whole library.
+   */
+  test('degrades to nothing pending when the change requests cannot be listed', async () => {
+    const workflow = {
+      listChangeRequests: async () => {
+        throw new Error('offline');
+      },
+    } as unknown as IWorkflowService;
+    const svc = new PendingSkillsService(
+      {} as unknown as WorkspaceService,
+      {} as unknown as IAccessControl,
+      { listSkills: async () => [] } as unknown as ISkillService,
+      workflow,
+    );
+    await expect(svc.listPendingSkills(AUTHOR)).resolves.toEqual([]);
+  });
+
+  test('oldest first — the request that has waited longest is the one to answer', async () => {
+    const svc = harness({
+      crs: [
+        cr({ number: 9, createdAt: '2026-08-06T12:00:00.000Z' }),
+        cr({
+          number: 3,
+          createdAt: '2026-08-01T12:00:00.000Z',
+          branch: 'agent/older',
+          touchedNodePaths: ['Groups/Engineering/older/SKILL.md'],
+        }),
+      ],
+      branchFiles: {
+        'agent/weekly-newsletter:Groups/Engineering/weekly-newsletter/SKILL.md': SKILL_MD,
+        'agent/older:Groups/Engineering/older/SKILL.md':
+          '---\nname: older\ndescription: Older.\n---\n',
+      },
+      writers: {
+        ...ADMIN_WRITES,
+        'Groups/Engineering/older/SKILL.md': [ADMIN],
+      },
+    });
+    expect((await svc.listPendingSkills(ADMIN)).map((p) => p.changeRequestNumber)).toEqual([3, 9]);
+  });
+});

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

@@ -50,14 +50,14 @@ describe('SkillService', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
-    const skills = join(root, wsId, KB_DIR, 'Skills');
+    const skills = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(join(skills, 'rfi', 'scripts'), { recursive: true });
     await writeFile(join(skills, 'rfi', 'SKILL.md'), RFI_SKILL);
     await writeFile(join(skills, 'rfi', 'scripts', 'build_xlsx.py'), 'print("xlsx")\n');
     // A folder with no SKILL.md is not a skill.
     await mkdir(join(skills, 'not-a-skill'), { recursive: true });
     await writeFile(join(skills, 'not-a-skill', 'README.md'), '# nope\n');
-    // A skill nested in a category subfolder (Skills/Development/coding-guidelines).
+    // A skill nested in a category subfolder (Groups/Development/coding-guidelines).
     await mkdir(join(skills, 'Development', 'coding-guidelines'), { recursive: true });
     await writeFile(
       join(skills, 'Development', 'coding-guidelines', 'SKILL.md'),
@@ -72,7 +72,7 @@ describe('SkillService', () => {
     expect(skills).toHaveLength(2);
     const rfi = skills.find((s) => s.name === 'rfi')!;
     expect(rfi).toBeDefined();
-    expect(rfi.path).toBe('Skills/rfi');
+    expect(rfi.path).toBe('Groups/rfi');
     expect(rfi.version).toBe('1.4.0');
     expect(rfi.description).not.toBe('|');
     expect(rfi.description).toContain('Specialist RFI responder');
@@ -83,19 +83,19 @@ describe('SkillService', () => {
     const skills = await svc().listSkills();
     const cg = skills.find((s) => s.name === 'coding-guidelines')!;
     expect(cg).toBeDefined();
-    expect(cg.path).toBe('Skills/Development/coding-guidelines');
+    expect(cg.path).toBe('Groups/Development/coding-guidelines');
     expect(cg.description).toBe('Coding guidelines.');
 
     const res = await svc().getSkill('user@x.eu', 'coding-guidelines');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'skill') {
-      expect(res.skill.path).toBe('Skills/Development/coding-guidelines');
+      expect(res.skill.path).toBe('Groups/Development/coding-guidelines');
       expect(res.skill.body).toContain('# Guidelines');
     }
   });
 
   test('refuses a colliding id (no auto-suffix) — the shared dedup rule', async () => {
-    const skills = join(root, wsId, KB_DIR, 'Skills');
+    const skills = join(root, wsId, KB_DIR, 'Groups');
     // Two skills resolve to the same id `dup` (no frontmatter id/name → folder name).
     await mkdir(join(skills, 'Zeta', 'dup'), { recursive: true });
     await writeFile(join(skills, 'Zeta', 'dup', 'SKILL.md'), '---\ndescription: zeta dup\n---\n\n# Z\n');
@@ -104,28 +104,28 @@ describe('SkillService', () => {
 
     const list = await svc().listSkills();
     // Only the first (smallest path) survives; the duplicate is dropped, not suffixed.
-    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Skills/Alpha/dup']);
+    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Groups/Alpha/dup']);
     expect(list.find((s) => s.name === 'dup2')).toBeUndefined();
 
     const a = await svc().getSkill('user@x.eu', 'dup');
-    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Skills/Alpha/dup');
+    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Groups/Alpha/dup');
   });
 
   test('frontmatter `id`/`name` overrides the folder name for identity', async () => {
-    const skills = join(root, wsId, KB_DIR, 'Skills');
+    const skills = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(join(skills, 'folderx'), { recursive: true });
     await writeFile(join(skills, 'folderx', 'SKILL.md'), '---\nid: my_skill\ndescription: d\n---\n\n# X\n');
     const list = await svc().listSkills();
-    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Skills/folderx');
+    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Groups/folderx');
   });
 
   test('getSkill returns body, folder path, files and allowed-tools', async () => {
     const res = await svc().getSkill('user@x.eu', 'rfi');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'skill') {
-      expect(res.skill.path).toBe('Skills/rfi');
+      expect(res.skill.path).toBe('Groups/rfi');
       expect(res.skill.body).toContain('# /rfi: Specialist RFI Responder');
-      expect(res.skill.files).toEqual(['Skills/rfi/scripts/build_xlsx.py']);
+      expect(res.skill.files).toEqual(['Groups/rfi/scripts/build_xlsx.py']);
       expect(res.skill.allowedTools).toEqual(['Bash', 'Read']);
     }
   });
@@ -134,7 +134,7 @@ describe('SkillService', () => {
     const res = await svc().getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'file') {
-      expect(res.file.path).toBe('Skills/rfi/scripts/build_xlsx.py');
+      expect(res.file.path).toBe('Groups/rfi/scripts/build_xlsx.py');
       expect(res.file.content).toContain('print("xlsx")');
     }
   });

package/src/modules/skills/index.ts

@@ -1,10 +1,13 @@
 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 type {
   ISkillService,
+  IPendingSkillService,
   Skill,
   SkillSummary,
   SkillFileContent,
+  PendingSkill,
   GetSkillResult,
 } from './skills.contract.js';