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

package/src/shared/__tests__/frontmatter-id.test.ts

@@ -56,6 +56,59 @@ describe('dedupeById', () => {
     expect(out.map((x) => x.at)).toEqual([1, 2]); // first `a` kept, second dropped
     expect(onDup).toHaveBeenCalledWith('a', 3);
   });
+
+  /**
+   * REGRESSION GUARD for the "one folder = one space" model.
+   *
+   * Spaces are grouping folders under the catalog root, and a tool or skill
+   * shared by two spaces is expected to be duplicated as two files with
+   * DISTINCT ids. Nothing enforces that convention — `seen` is a single
+   * global Set keyed on the declared id, with no notion of the folder the
+   * item came from. So the moment two spaces hold a same-named item, one of
+   * them silently disappears from the catalog.
+   *
+   * These tests pin that behaviour so it is a documented, observable
+   * property rather than a surprise. If dedup ever becomes folder-scoped,
+   * they are the tests that should change.
+   */
+  test('same id in two different space folders: the second folder loses its copy', () => {
+    const onDup = vi.fn();
+    // Services sort by (name, path) before deduping, so path order is stable.
+    const items = [
+      { name: 'notion', path: 'Tools/Everyone/notion.tool' },
+      { name: 'notion', path: 'Tools/Finance/notion.tool' },
+    ];
+    const out = dedupeById(items, (x) => x.name, (x, id) => onDup(id, x.path));
+
+    expect(out).toHaveLength(1);
+    expect(out[0].path).toBe('Tools/Everyone/notion.tool');
+    // The Finance space loses its tool entirely — only a server-side warning
+    // marks it, which is why the convention needs distinct ids per space.
+    expect(onDup).toHaveBeenCalledWith('notion', 'Tools/Finance/notion.tool');
+  });
+
+  test('distinct ids per space folder keep BOTH copies — the supported pattern', () => {
+    const onDup = vi.fn();
+    const items = [
+      { name: 'everyone_notion', path: 'Tools/Everyone/notion.tool' },
+      { name: 'finance_notion', path: 'Tools/Finance/notion.tool' },
+    ];
+    const out = dedupeById(items, (x) => x.name, (x, id) => onDup(id, x.path));
+
+    expect(out).toHaveLength(2);
+    expect(onDup).not.toHaveBeenCalled();
+  });
+
+  test('the surviving copy is the alphabetically-first path, not scan order', () => {
+    // Deterministic winner matters: an unstable one means a space's tool
+    // appears or vanishes depending on filesystem iteration order.
+    const items = [
+      { name: 'x', path: 'Tools/Zulu/x.tool' },
+      { name: 'x', path: 'Tools/Alpha/x.tool' },
+    ].sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+
+    expect(dedupeById(items, (i) => i.name)[0].path).toBe('Tools/Alpha/x.tool');
+  });
 });
 
 describe('setFrontmatterField (shared, line-based)', () => {

package/src/shared/__tests__/join-request.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { isJoinBranchFor, joinBranchFor, kebabGroupName } from '@bevel-software/platform-shared';
+import { assertValidBranchName } from '../../modules/workflow/git/branch-name.js';
+
+/**
+ * The join-branch convention. Two properties matter, and they pull in
+ * different directions:
+ *
+ *  - UNIQUENESS (the write side): distinct requesters and distinct groups must
+ *    never share a branch, or one person's commit lands on another's request.
+ *    Both inputs the name is built from are lossy; the requester tag fixes it.
+ *  - EXACT GROUP IDENTITY (the read side): the settle decision is "the diff
+ *    is empty", so matching a branch to the WRONG group reads an unchanged
+ *    file, sees an empty diff, and destroys somebody else's request. The
+ *    group tag is recomputed from the exact name so shape-matching can never
+ *    cross groups; only the requester half matches by shape (the reader has
+ *    no email to recompute it from).
+ */
+const TAG = '[0-9a-z]{7}';
+
+describe('joinBranchFor', () => {
+  it('produces a valid branch name that follows the draft convention', () => {
+    const branch = joinBranchFor('ali@bevel.software', 'GTM');
+    expect(branch).toMatch(new RegExp(`^ali/join-gtm-${TAG}-${TAG}$`));
+    expect(() => assertValidBranchName(branch)).not.toThrow();
+  });
+
+  it('is deterministic, and case-insensitive in the email only', () => {
+    expect(joinBranchFor('Ali@Bevel.Software', 'GTM')).toBe(joinBranchFor('ali@bevel.software', 'GTM'));
+  });
+
+  it('separates requesters who share a localpart across domains', () => {
+    // Regression: without the requester tag both collapse to one branch, so
+    // the second requester's grant commit lands on the first one's branch.
+    expect(joinBranchFor('ali@bevel.software', 'GTM')).not.toBe(
+      joinBranchFor('ali@other.com', 'GTM'),
+    );
+  });
+
+  it('separates groups whose names kebab to the same slug', () => {
+    expect(joinBranchFor('ali@bevel.software', 'Finance!')).not.toBe(
+      joinBranchFor('ali@bevel.software', 'Finance'),
+    );
+    // Case is part of a group's identity (the folder name is case-sensitive).
+    expect(joinBranchFor('ali@bevel.software', 'finance')).not.toBe(
+      joinBranchFor('ali@bevel.software', 'Finance'),
+    );
+  });
+
+  it('still yields a valid, matchable branch for a group with no alphanumerics', () => {
+    const branch = joinBranchFor('ali@bevel.software', '!!!');
+    expect(kebabGroupName('!!!')).toBe('');
+    expect(branch).toMatch(new RegExp(`^ali/join-${TAG}-${TAG}$`));
+    expect(() => assertValidBranchName(branch)).not.toThrow();
+    expect(isJoinBranchFor(branch, '!!!')).toBe(true);
+  });
+});
+
+describe('isJoinBranchFor', () => {
+  it("recognises somebody ELSE's join branch (the requester tag is not recomputed)", () => {
+    expect(isJoinBranchFor(joinBranchFor('juan@bevel.software', 'GTM'), 'GTM')).toBe(true);
+    expect(isJoinBranchFor(joinBranchFor('ali@other.com', 'GTM'), 'GTM')).toBe(true);
+  });
+
+  it('rejects a branch for a different group', () => {
+    expect(isJoinBranchFor(joinBranchFor('ali@bevel.software', 'Finance'), 'GTM')).toBe(false);
+  });
+
+  it('NEVER crosses slug-colliding groups — the destructive-settle regression', () => {
+    // `Finance!`, `finance` and `Finance` all slug to `finance`. A listing
+    // for one that matched another's branch would read that branch's copy of
+    // ITS OWN access.md (unchanged there), see an empty diff, and settle —
+    // closing a change request and deleting a branch belonging to a
+    // different group. The recomputed group tag is what forbids the match.
+    const forBang = joinBranchFor('ali@bevel.software', 'Finance!');
+    expect(isJoinBranchFor(forBang, 'finance')).toBe(false);
+    expect(isJoinBranchFor(forBang, 'Finance')).toBe(false);
+    expect(isJoinBranchFor(forBang, 'Finance!')).toBe(true);
+    expect(isJoinBranchFor(joinBranchFor('ali@bevel.software', 'finance'), 'Finance!')).toBe(false);
+  });
+
+  it('rejects ordinary draft branches and near-misses', () => {
+    const good = joinBranchFor('ali@bevel.software', 'GTM');
+    const [, suffix] = good.split('/');
+    for (const branch of [
+      'ali/gtm',
+      'ali/join-gtm', // no tags — the pre-tag shape
+      'ali/join-gtm-abc1234', // one tag only
+      `ali/${suffix.toUpperCase()}`, // tags are lowercase base36
+      `ali/${suffix}/extra`,
+      suffix, // no author segment
+    ]) {
+      expect(isJoinBranchFor(branch, 'GTM'), branch).toBe(false);
+    }
+  });
+});

package/src/shared/__tests__/kb-layout.group.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { groupOfPath, GROUPS_DIR } from '@bevel-software/platform-shared';
+
+/**
+ * `groupOfPath` is the whole of the grouping contract — the sidebar, the
+ * catalog buckets and the access story all read a group off a path with it.
+ * The cases that matter are the ones where "has a group" and "is under the
+ * group root" come apart.
+ */
+describe('groupOfPath', () => {
+  it('reads the group from the Groups root', () => {
+    expect(groupOfPath(`${GROUPS_DIR}/GTM/heyreach-campaign/SKILL.md`)).toBe('GTM');
+    expect(groupOfPath(`${GROUPS_DIR}/GTM/heyreach.tool`)).toBe('GTM');
+    expect(groupOfPath(`${GROUPS_DIR}/Engineering/review/architecture-review`)).toBe(
+      'Engineering',
+    );
+  });
+
+  it('returns null for content directly under the root — it has no group folder', () => {
+    // The regression this guards: `Groups/slack.tool` must NOT report a group
+    // called "slack.tool", and `Groups/GTM` must not report itself.
+    expect(groupOfPath(`${GROUPS_DIR}/slack.tool`)).toBeNull();
+    expect(groupOfPath(`${GROUPS_DIR}/GTM`)).toBeNull();
+    expect(groupOfPath(GROUPS_DIR)).toBeNull();
+  });
+
+  it('returns null outside the group root', () => {
+    expect(groupOfPath('KnowledgeBase/Product/Knowledge/Foo.md')).toBeNull();
+    expect(groupOfPath('Data/Engineering/Knowledge/Bar.md')).toBeNull();
+    // The retired pre-merge roots are ordinary non-group folders now.
+    expect(groupOfPath('Skills/GTM/heyreach-campaign')).toBeNull();
+    expect(groupOfPath('Tools/NewsAgent/serper.tool')).toBeNull();
+    expect(groupOfPath('access.md')).toBeNull();
+    expect(groupOfPath('')).toBeNull();
+  });
+
+  it('is not fooled by a prefix match on the root name', () => {
+    expect(groupOfPath('GroupsOld/GTM/x')).toBeNull();
+  });
+
+  it('tolerates leading and doubled separators', () => {
+    expect(groupOfPath(`/${GROUPS_DIR}/GTM/x`)).toBe('GTM');
+    expect(groupOfPath(`${GROUPS_DIR}//GTM//x`)).toBe('GTM');
+  });
+});

package/src/shared/kb-layout.test.ts

@@ -41,8 +41,8 @@ describe('ontologyOf', () => {
     expect(ontologyOf('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
   });
 
-  it('returns null for Skills and root config (neutral)', () => {
-    expect(ontologyOf('Skills/some-skill/SKILL.md')).toBeNull();
+  it('returns null for Groups and root config (neutral)', () => {
+    expect(ontologyOf('Groups/some-skill/SKILL.md')).toBeNull();
     expect(ontologyOf('access.md')).toBeNull();
     expect(ontologyOf('roles.yaml')).toBeNull();
   });

package/src/test-setup.ts

@@ -0,0 +1,18 @@
+import { branchModelFromEnv, configureBranchModel } from '@bevel-software/platform-shared';
+
+/**
+ * Apply the branch model before any suite imports something that reads it.
+ *
+ * The shared module no longer reads `process.env` at import time — both sides
+ * configure it during boot instead (`createCoreServices` here, a fetch of
+ * `/api/config` in the browser). Suites exercise pieces of the server without
+ * going through `createCoreServices`, so the same call has to happen for them.
+ *
+ * It must live in `setupFiles` rather than `vitest.config.ts`: the config is
+ * evaluated in its own module graph, so a call there configures a copy of the
+ * shared module that no test ever sees.
+ *
+ * The values come from the environment the config pins, which keeps the one
+ * place the historical two-branch pair is written.
+ */
+configureBranchModel(branchModelFromEnv());

package/kb-template/Agents/README.md

@@ -1,38 +0,0 @@
-# Agents/
-
-`.agent` files — **role definitions for agents**, and the main way anyone
-(a person's own assistant or a background pipeline) connects to the platform.
-Connecting "as" an `.agent` mints exactly that agent's tool surface — e.g. the
-KB's MCP config is generated per `.agent`, not from everything the identity
-can read.
-
-## Structure
-
-```text
-Agents/
-├── default.agent         ← the safe floor: basic KB access only
-├── developer.agent       ← an admin-authored role: everything developers get
-└── <role-or-pipeline>.agent
-```
-
-One file per role or per pipeline agent. (Exact file format: TBD.)
-
-## What an `.agent` defines
-
-- The **target harness** (e.g. Claude Code) and model / reasoning settings.
-- The **skills** and **tools** composed in — selections from `Skills/` and
-  `Tools/`. The execution layer compiles these into the harness's native
-  plugin format and installs it.
-- Permissions/allowlists, hooks, MCP servers, env vars, session defaults,
-  and injected instructions (the agent's charter).
-- **References** to an identity and a budget — never credentials themselves.
-
-## Rules
-
-- An `.agent` only **narrows** what its identity's permissions already allow —
-  it never widens access. Identity remains the security boundary; `.agent`
-  is configuration.
-- **No secret values** in these files — secrets are referenced by vault name.
-- This folder sits under access control + change requests: editing a role
-  file changes the whole role's tooling, and is reviewed like any other
-  change.