@bevel-software/platform-core-backend 0.4.1 → 0.5.1

package/src/modules/groups/groups.routes.ts

@@ -0,0 +1,433 @@
+import express from 'express';
+import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import {
+  DEFAULT_BRANCH,
+  joinBranchFor,
+  type AuthUser,
+  type ChangeRequest,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { spliceGrant } from '../access/access-splice.js';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { groupsWorkspaceId } from './groups.service.js';
+import { GroupProvisionError, type GroupProvisionService } from './group-provision.service.js';
+import type { JoinRequestsService } from './join-requests.service.js';
+import type {
+  GroupCatalogEntry,
+  GroupSummary,
+  IGroupIndexService,
+} from './groups.contract.js';
+
+/**
+ * Browser-facing (JWT) group routes, mounted behind `authMiddleware`:
+ *
+ *   GET    /api/groups                            → { groups: GroupSummary[] }
+ *   DELETE /api/groups/:name                      → { ok }          (owners)
+ *   POST   /api/groups/:name/join-request         → { ok, number }  (opens a CR)
+ *   GET    /api/groups/:name/join-requests        → { requests }    (managers)
+ *   POST   /api/groups/:name/join-requests/:n/reconcile → { closed }
+ *
+ * Enumeration is three verdicts per (caller, group), all of them ordinary
+ * access resolution — no special cases, no side tables:
+ *
+ *   member       canRead on the group FOLDER
+ *   manager      canWrite on the folder's access.md (admin-rescued)
+ *   discoverable canRead on the access.md FILE — in the body-governed format
+ *                its own `read: everyone` frontmatter grants this
+ *
+ * All three false ⇒ the group is absent from the response entirely.
+ *
+ * A join request is a plain change request whose branch edits the group's
+ * `access.md`. Managers do NOT merge it: they read its individual proposals
+ * (see `join-proposals.ts`), grant the ones they accept through the ordinary
+ * access path, and the request retires itself once its rules are a subset of
+ * the default branch's — reconciled here, lazily on listing and eagerly right
+ * after a grant. Nothing about the lifecycle is stored; it is derived from
+ * two copies of one file.
+ *
+ * Auth gating is explicit and uniform: `authMiddleware` at the mount, PLUS a
+ * `req.userEmail` check in every handler (the skills-routes pattern) so a
+ * middleware change can never silently un-gate one. Nothing here is reachable
+ * with an agent connection key or a manual-auth bearer.
+ */
+export function createGroupsRoutes(
+  groupIndex: IGroupIndexService,
+  accessControl: IAccessControl,
+  workflow: IWorkflowService,
+  workspaceService: WorkspaceService,
+  joinRequests: JoinRequestsService,
+  provision: GroupProvisionService,
+  kbDirName: string,
+  resolveUser: (req: express.Request) => Promise<AuthUser | null>,
+): express.Router {
+  const router = express.Router();
+
+  /** The folder-chain probe for MEMBERSHIP — the folder itself. */
+  const memberProbe = (folder: string) => folder;
+  /** The FILE probe for discovery/management — the folder's access.md. */
+  const accessMdOf = (folder: string) => `${folder}/access.md`;
+
+  const probesFor = (groups: GroupCatalogEntry[]): string[] => [
+    ...new Set(groups.flatMap((g) => g.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]))),
+  ];
+
+  /** The caller's open join CR for `group`, or null. */
+  const openJoinCr = (mine: ChangeRequest[], email: string, group: string): ChangeRequest | null =>
+    mine.find((cr) => cr.state === 'open' && cr.branch === joinBranchFor(email, group)) ?? null;
+
+  router.get('/groups', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    try {
+      const catalog = await groupIndex.catalog();
+      if (catalog.length === 0) {
+        res.json({ groups: [] });
+        return;
+      }
+      const wsId = groupsWorkspaceId();
+      const probes = probesFor(catalog);
+      const [readable, writable, owned] = await Promise.all([
+        accessControl.canReadBatch(wsId, email, probes),
+        accessControl.canWriteBatch(wsId, email, probes),
+        accessControl.canOwnerBatch(wsId, email, probes),
+      ]);
+      // Fail closed on every verdict: a path missing from the map is denied.
+      const any = (map: Map<string, boolean>, g: GroupCatalogEntry, probe: (f: string) => string) =>
+        g.folders.some((f) => map.get(probe(f)) === true);
+
+      // The caller's own open join CRs — drives `hasRequested`. A CR-listing
+      // hiccup must not take group enumeration down: degrade to "nothing
+      // requested" and let the next load repair it.
+      let mine: ChangeRequest[] = [];
+      try {
+        mine = await workflow.listChangeRequestsAuthoredBy(email);
+      } catch (err) {
+        console.warn(
+          `[groups] join-request lookup failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      const groups: GroupSummary[] = [];
+      for (const g of catalog) {
+        const member = any(readable, g, memberProbe);
+        const manager = any(writable, g, accessMdOf);
+        // The FOLDER verdict, owner-lists-only — the delete gate, mirrored
+        // here so the UI shows the verb to exactly the people the DELETE
+        // route will let through.
+        const owner = any(owned, g, memberProbe);
+        const discoverable = member || any(readable, g, accessMdOf);
+        if (!member && !manager && !discoverable) continue; // absent — fail closed
+        const joinCr = member ? null : openJoinCr(mine, email, g.name);
+        groups.push({
+          name: g.name,
+          folders: g.folders,
+          canRead: member,
+          canWrite: manager,
+          isOwner: owner,
+          skillCount: g.skillCount,
+          toolCount: g.toolCount,
+          owners: g.owners,
+          writers: g.writers,
+          readers: g.readers,
+          hasRequested: joinCr !== null,
+          requestNumber: joinCr?.number ?? null,
+        });
+      }
+      res.json({ groups });
+    } catch (err) {
+      console.error('[groups] failed to list groups:', err);
+      res.status(500).json({ error: 'Failed to list groups' });
+    }
+  });
+
+  /**
+   * Open (or return the existing) join change request for the caller.
+   *
+   * Idempotent via the deterministic branch name: a second click finds the
+   * open CR and returns it. Every step is an existing primitive — branch,
+   * splice, commit-and-push, open CR — so the security story is exactly the
+   * workflow's: draft branches are ungated, and the merge gate requires an
+   * approver who can write the touched access.md.
+   */
+  /**
+   * Create a group — the ONE door through which `Groups/<name>/` folders come
+   * to exist. Any authenticated user may create one; that is the product
+   * model (making a group makes you the one who runs it), and the seeded
+   * access.md immediately fences the new folder off from everyone else. See
+   * `GroupProvisionService` for why this is an endpoint and not a write path.
+   */
+  router.post('/groups', async (req, res) => {
+    const user = await resolveUser(req);
+    if (!user) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    // `req.body` is undefined when no JSON body was sent at all — that is a
+    // 400, not a destructuring crash.
+    const { name } = (req.body ?? {}) as { name?: string };
+    if (typeof name !== 'string') {
+      res.status(400).json({ error: 'name is required in body' });
+      return;
+    }
+    try {
+      const result = await provision.createGroup(user, name);
+      res.status(201).json(result);
+    } catch (err) {
+      if (err instanceof GroupProvisionError) {
+        res.status(err.status).json({ error: err.message });
+        return;
+      }
+      console.error('[groups] create failed:', err);
+      res.status(500).json({ error: 'Failed to create the group' });
+    }
+  });
+
+  /**
+   * Ensure the caller's personal folder (`Groups/personal-<id>/`) exists —
+   * idempotent; the UI calls it lazily right before the first personal-skill
+   * write. Private by construction: its access.md names only the caller.
+   */
+  router.post('/groups/personal', async (req, res) => {
+    const user = await resolveUser(req);
+    if (!user) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    try {
+      res.json(await provision.ensurePersonalGroup(user));
+    } catch (err) {
+      console.error('[groups] personal-folder ensure failed:', err);
+      res.status(500).json({ error: 'Failed to prepare your personal folder' });
+    }
+  });
+
+  /**
+   * Delete a group — the OWNER's verb, and only theirs. Creating a group
+   * makes you the one who runs it; deleting it is the other end of that same
+   * promise, so the gate is the `owner` verdict on the folder (owner-lists
+   * only, no admin rescue) — a manager who merely writes the access.md, and
+   * an admin rescued into managing it, do not get it.
+   *
+   * Fail-closed like every other group surface: an unknown group and a group
+   * the caller does not own answer IDENTICALLY, so probing the endpoint can
+   * confirm nothing about what exists. The mechanism (park, one commit,
+   * rollback on refusal) lives in `GroupProvisionService.deleteGroup`.
+   */
+  router.delete('/groups/:name', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    try {
+      const user = await resolveUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      // Case-sensitive, like `groupOfPath` — the group name IS the folder name.
+      const group = (await groupIndex.catalog()).find((g) => g.name === req.params.name);
+      const wsId = groupsWorkspaceId();
+      const ownerVerdicts = group
+        ? await Promise.all(
+            group.folders.map((f) => accessControl.canOwner(wsId, email, memberProbe(f))),
+          )
+        : [];
+      if (!group || !ownerVerdicts.some((v) => v === true)) {
+        res.status(404).json({ error: 'Unknown group', kind: 'unknown-group' });
+        return;
+      }
+      await provision.deleteGroup(user, group.name);
+      groupIndex.invalidate();
+      res.json({ ok: true });
+    } catch (err) {
+      if (err instanceof GroupProvisionError) {
+        res.status(err.status).json({ error: err.message });
+        return;
+      }
+      console.error('[groups] delete failed:', err);
+      res.status(500).json({ error: 'Failed to delete the group' });
+    }
+  });
+
+  router.post('/groups/:name/join-request', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    try {
+      const user = await resolveUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const catalog = await groupIndex.catalog();
+      // Case-sensitive, like `groupOfPath` — the group name IS the folder name.
+      const group = catalog.find((g) => g.name === req.params.name);
+      const wsId = groupsWorkspaceId();
+      // Same ANY-folder shape `GET /groups` resolves with, so a group can
+      // never be listed as discoverable there and rejected as unknown here.
+      const verdicts = group
+        ? await accessControl.canReadBatch(
+            wsId,
+            email,
+            group.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]),
+          )
+        : new Map<string, boolean>();
+      const any = (probe: (f: string) => string) =>
+        group?.folders.some((f) => verdicts.get(probe(f)) === true) ?? false;
+      // Discovery gate, fail-closed: an unknown group and a group the caller
+      // cannot discover answer IDENTICALLY, so probing can't confirm existence.
+      if (!group || !any(accessMdOf)) {
+        res.status(404).json({ error: 'Unknown group', kind: 'unknown-group' });
+        return;
+      }
+      if (any(memberProbe)) {
+        // Access landed between page load and click — reload, don't ask.
+        res.status(409).json({ error: 'You can already read this group', kind: 'already-readable' });
+        return;
+      }
+      // The grant is written to the group's primary folder — the one the
+      // summary's `folders[0]` names and the banner's touched-path check
+      // expects.
+      const folder = group.folders[0];
+
+      const branch = joinBranchFor(email, group.name);
+      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, group.name);
+      if (existing) {
+        res.json({ ok: true, number: existing.number });
+        return;
+      }
+
+      // A leftover branch from a rejected/withdrawn request is reused — the
+      // grant commit is already on it and the splice below no-ops.
+      try {
+        await workflow.createBranch(groupsWorkspaceId(), branch, DEFAULT_BRANCH);
+      } catch {
+        // exists (or raced) — proceed against it
+      }
+      const ws = await workspaceService.getOrCreateForBranch(branch);
+      const accessPath = `${kbDirName}/${accessMdOf(folder)}`;
+      const current = await workspaceService.readFile(ws.id, accessPath).catch(() => '');
+      const spliced = spliceGrant(
+        current,
+        'read',
+        { kind: 'user', email: user.email, displayName: user.name },
+        { target: 'folder' },
+      );
+      if (spliced.changed) {
+        await workspaceService.writeFile(ws.id, accessPath, spliced.text);
+        await workflow.commitChanges(ws.id, user, `Request access to ${group.name}`);
+      }
+      const detail = await workflow.openChangeRequest(ws.id, user, {
+        sourceBranch: branch,
+        targetBranch: DEFAULT_BRANCH,
+        title: `Join request: ${group.name}`,
+        description:
+          `${user.name} asked to join ${group.name}. A manager of the group accepts by ` +
+          `granting the access this branch proposes; the request closes itself once ` +
+          `every proposal has landed.`,
+      });
+      res.json({ ok: true, number: detail.number });
+    } catch (err) {
+      if (err instanceof WorkflowDomainError) {
+        res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+        return;
+      }
+      console.error('[groups] failed to open a join request:', err);
+      res.status(500).json({ error: 'Failed to request access' });
+    }
+  });
+
+  /**
+   * Resolve the caller as a MANAGER of `name` — the only role that may see or
+   * settle its join requests. Returns the group's primary folder, or null
+   * after answering the request.
+   *
+   * A non-manager gets an empty list rather than a 403 (the frontend asks
+   * unconditionally, exactly as it does for every other group surface), and
+   * an unknown group is indistinguishable from an unmanaged one.
+   */
+  async function requireManager(
+    req: express.Request,
+    res: express.Response,
+    onDenied: () => void,
+  ): Promise<{ group: GroupCatalogEntry; folder: string; user: AuthUser } | null> {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return null;
+    }
+    const group = (await groupIndex.catalog()).find((g) => g.name === req.params.name);
+    if (!group) {
+      onDenied();
+      return null;
+    }
+    const writable = await accessControl.canWriteBatch(
+      groupsWorkspaceId(),
+      email,
+      group.folders.map(accessMdOf),
+    );
+    if (!group.folders.some((f) => writable.get(accessMdOf(f)) === true)) {
+      onDenied();
+      return null;
+    }
+    const user = await resolveUser(req);
+    if (!user) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return null;
+    }
+    return { group, folder: group.folders[0], user };
+  }
+
+  router.get('/groups/:name/join-requests', async (req, res) => {
+    try {
+      const ctx = await requireManager(req, res, () => res.json({ requests: [] }));
+      if (!ctx) return;
+      const crs = await workflow.listChangeRequests();
+      res.json({
+        requests: await joinRequests.list(ctx.group.name, ctx.folder, crs, ctx.user),
+      });
+    } catch (err) {
+      console.error('[groups] failed to list join requests:', err);
+      res.status(500).json({ error: 'Failed to list join requests' });
+    }
+  });
+
+  /**
+   * Settle one request if its proposals have all landed on the default
+   * branch. Called right after a grant so the banner updates in the same
+   * round-trip; the listing does the same thing lazily, so skipping this (a
+   * dropped response, a closed tab) only delays it.
+   */
+  router.post('/groups/:name/join-requests/:number/reconcile', async (req, res) => {
+    try {
+      const ctx = await requireManager(req, res, () =>
+        res.status(404).json({ error: 'Not found' }),
+      );
+      if (!ctx) return;
+      const crNumber = Number(req.params.number);
+      if (!Number.isSafeInteger(crNumber) || crNumber <= 0) {
+        res.status(400).json({ error: 'Invalid change request number' });
+        return;
+      }
+      const cr = await workflow.getChangeRequest(crNumber);
+      if (!cr) {
+        res.status(404).json({ error: 'Not found' });
+        return;
+      }
+      res.json({ closed: await joinRequests.reconcile(ctx.group.name, ctx.folder, cr, ctx.user) });
+    } catch (err) {
+      console.error('[groups] failed to reconcile a join request:', err);
+      res.status(500).json({ error: 'Failed to update the request' });
+    }
+  });
+
+  return router;
+}

package/src/modules/groups/groups.service.ts

@@ -0,0 +1,193 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import type { Dirent } from 'node:fs';
+import {
+  DEFAULT_BRANCH,
+  GROUPS_DIR,
+  groupOfPath,
+  isPersonalGroupFolder,
+} from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import type { ISkillService } from '../skills/skills.contract.js';
+import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import { TtlCache } from '../../shared/ttl-cache.js';
+import type { GroupCatalogEntry, IGroupIndexService } from './groups.contract.js';
+
+const CACHE_TTL_MS = 60_000;
+
+/**
+ * The group index: every group folder in the default-branch KB, with its
+ * caller-independent totals and access principals.
+ *
+ * Two decisions worth keeping straight:
+ *
+ *  - **Existence is an `access.md`, counting is not.** A group EXISTS because
+ *    its folder carries an `access.md` — the file the provisioning endpoint
+ *    seeds and the one every per-caller verdict (member / manager /
+ *    discoverable) resolves against. A bare directory under `Groups/` is NOT
+ *    a group: git cannot record an empty folder, so deleting a group's files
+ *    leaves its directory behind on live checkouts, and enumerating by
+ *    directory would resurrect every such ghost. Counts come from the
+ *    already-cached global catalogs — `skillService.listSkills(undefined)` and
+ *    `toolManualService.listAllSummaries()` — bucketed by `groupOfPath`. A
+ *    second `walkFiles` pass would re-read the same tree and could disagree
+ *    with the catalogs about what counts as a skill.
+ *  - **Loose files are not groups.** `Groups/slack.tool` sits directly under
+ *    the root, so it is a file, not a directory — the same ≥3-segment rule
+ *    `groupOfPath` applies, arrived at from the other side.
+ *
+ * Cached for {@link CACHE_TTL_MS} and dropped by `invalidate()` from the
+ * file-change subscriber, so a grant committed on the default branch is
+ * reflected within one round-trip rather than one TTL.
+ */
+export class GroupIndexService implements IGroupIndexService {
+  private readonly cache: TtlCache<GroupCatalogEntry[]>;
+
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly accessControl: IAccessControl,
+    private readonly skillService: ISkillService,
+    private readonly toolManualService: IToolManualService,
+    private readonly kbDirName: string,
+    now: () => number = Date.now,
+  ) {
+    this.cache = new TtlCache(CACHE_TTL_MS, now);
+  }
+
+  invalidate(): void {
+    this.cache.invalidate();
+  }
+
+  async catalog(): Promise<GroupCatalogEntry[]> {
+    const cached = this.cache.get();
+    if (cached) return cached;
+    const entries = await this.build();
+    // A failed scan and a KB with genuinely no group folders both serve `[]`,
+    // but only the second is a fact worth holding for the TTL. Caching the
+    // failure would hide every group from every user for the full 60s AFTER
+    // the cause is gone — a clone mid-creation, a readdir that raced a
+    // checkout — and `invalidate()` only fires on a file-change event that may
+    // never arrive in that window. So a degraded read is served, not stored,
+    // and the next caller retries.
+    if (entries === null) return [];
+    this.cache.set(entries);
+    return entries;
+  }
+
+  // --- internal --------------------------------------------------------------
+
+   /**
+   * Degrades on ANY failure rather than throwing. The Library must never break
+   * because a group folder can't be read — same philosophy as the skill and
+   * tool-manual scanners, and the reason the route's 500 is reserved for the
+   * per-caller half.
+   *
+   * `null` is that degraded case and is deliberately NOT the same value as an
+   * empty array: a KB with no group folders returns `[]`, which is true and
+   * cacheable, while a failure returns `null`, which `catalog()` serves as `[]`
+   * without storing it.
+   */
+  private async build(): Promise<GroupCatalogEntry[] | null> {
+    try {
+      const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+      const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+
+      const folders = await this.scanFolders(kbRoot);
+      if (folders.size === 0) return [];
+
+      const [skillCounts, toolCounts] = await Promise.all([
+        this.countSkills(),
+        this.countTools(),
+      ]);
+
+      const entries: GroupCatalogEntry[] = [];
+      for (const [name, groupFolders] of folders) {
+        // One folder, one access boundary — the folder IS the group.
+        const [primary] = groupFolders;
+        const [owners, writers, readers] = await Promise.all([
+          this.accessControl.eligibleOwners(wsId, primary),
+          this.accessControl.eligibleWriters(wsId, primary),
+          this.accessControl.eligibleReaders(wsId, primary),
+        ]);
+        entries.push({
+          name,
+          folders: groupFolders,
+          skillCount: skillCounts.get(name) ?? 0,
+          toolCount: toolCounts.get(name) ?? 0,
+          owners,
+          writers,
+          readers,
+        });
+      }
+      return entries.sort((a, b) => a.name.localeCompare(b.name));
+    } catch (err) {
+      console.warn(
+        `[groups] group index unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return null;
+    }
+  }
+
+  /** name → repo-relative group folder (always a single-element list). */
+  private async scanFolders(kbRoot: string): Promise<Map<string, string[]>> {
+    const byName = new Map<string, string[]>();
+    let children: Dirent[];
+    try {
+      children = await fs.readdir(path.join(kbRoot, GROUPS_DIR), { withFileTypes: true });
+    } catch {
+      return byName; // a KB without a `Groups/` root simply has no groups
+    }
+    const candidates = children.filter(
+      (child) =>
+        child.isDirectory() &&
+        !child.name.startsWith('.') &&
+        // Personal folders live under Groups/ but are not groups: one exists
+        // per person, private by construction, and listing them would put a
+        // locked row per employee in everyone's index.
+        !isPersonalGroupFolder(child.name),
+    );
+    // A group exists exactly when its folder carries an `access.md` (see the
+    // class doc) — stat that file, don't trust the directory.
+    const verdicts = await Promise.all(
+      candidates.map(async (child) => {
+        try {
+          return (await fs.stat(path.join(kbRoot, GROUPS_DIR, child.name, 'access.md'))).isFile();
+        } catch {
+          return false;
+        }
+      }),
+    );
+    candidates.forEach((child, i) => {
+      if (verdicts[i]) byName.set(child.name, [`${GROUPS_DIR}/${child.name}`]);
+    });
+    return byName;
+  }
+
+  private async countSkills(): Promise<Map<string, number>> {
+    // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
+    // property of the group, not of who is asking.
+    return bucketByGroup(await this.skillService.listSkills(undefined));
+  }
+
+  private async countTools(): Promise<Map<string, number>> {
+    return bucketByGroup(await this.toolManualService.listAllSummaries());
+  }
+}
+
+/** Count items per group folder name; ungrouped items (`null`) count nowhere. */
+function bucketByGroup(items: { path: string }[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const item of items) {
+    const group = groupOfPath(item.path);
+    if (group === null) continue;
+    counts.set(group, (counts.get(group) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/** The default-branch workspace id every group resolution runs against. */
+export function groupsWorkspaceId(): string {
+  return workspaceIdForBranch(DEFAULT_BRANCH);
+}

package/src/modules/groups/index.ts

@@ -0,0 +1,17 @@
+export { GroupIndexService, groupsWorkspaceId } from './groups.service.js';
+export {
+  GroupProvisionService,
+  GroupProvisionError,
+  groupAccessMd,
+  personalAccessMd,
+} from './group-provision.service.js';
+export { JoinRequestsService, type JoinRequest } from './join-requests.service.js';
+export { pendingProposals, type JoinProposal } from './join-proposals.js';
+export { createGroupsRoutes } from './groups.routes.js';
+export type {
+  IGroupIndexService,
+  GroupCatalogEntry,
+  GroupSummary,
+  ResolvedPrincipals,
+  ResolvedReaders,
+} from './groups.contract.js';