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

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

@@ -1,10 +1,11 @@
 import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { mkdtemp, rm, mkdir, writeFile, cp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { SkillService } from '../skills.service.js';
+import { SkillService, unmergedSkillNotice } from '../skills.service.js';
+import { BranchNotFoundError } from '../../../shared/domain-errors.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -38,11 +39,20 @@ You answer RFIs.
 
 describe('SkillService', () => {
   let root: string;
+  /**
+   * The branches that have a clone under `root`. A name that is not in here
+   * answers the way the real service does for a branch nobody ever pushed: the
+   * 404 the file tools answer, not an empty workspace.
+   */
+  let clones: Set<string>;
 
-  // WorkspaceService stub: default-branch workspace lives at <root>/<wsId>, the
-  // KB clone at <root>/<wsId>/<KB_DIR>.
+  // WorkspaceService stub: a branch's workspace lives at <root>/<branch's id>,
+  // its KB clone at <root>/<id>/<KB_DIR>.
   const workspaceService = {
-    getOrCreateForBranch: async () => ({ id: wsId }),
+    getOrCreateForBranch: async (branch: string) => {
+      if (!clones.has(branch)) throw new BranchNotFoundError(branch);
+      return { id: workspaceIdForBranch(branch) };
+    },
     getWorkspacePath: async (id: string) => join(root, id),
     readFile: async (id: string, rel: string) => fsReadFile(join(root, id, rel), 'utf-8'),
   } as unknown as WorkspaceService;
@@ -58,6 +68,7 @@ describe('SkillService', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
+    clones = new Set([DEFAULT_BRANCH]);
     const skills = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(join(skills, 'rfi', 'scripts'), { recursive: true });
     await writeFile(join(skills, 'rfi', 'SKILL.md'), RFI_SKILL);
@@ -480,4 +491,217 @@ describe('SkillService', () => {
       });
     });
   });
+
+  /**
+   * Reading a DRAFT branch: what an agent needs to try the skill it has just
+   * written, with the answer saying plainly that nobody approved it.
+   *
+   * The draft starts as a copy of the released tree — which is what a clone of
+   * a branch with no skill changes on it is — and each test changes it.
+   */
+  describe('reading a branch', () => {
+    const DRAFT = 'juan/skill-deck';
+    const draftWsId = workspaceIdForBranch(DRAFT);
+    const user = 'user@x.eu';
+    const draftKb = () => join(root, draftWsId, KB_DIR);
+    const named = async (service = svc()) =>
+      Object.fromEntries((await service.listSkills(user, { branch: DRAFT })).map((s) => [s.name, s]));
+
+    const writeDeck = (body = '# Deck\n') =>
+      mkdir(join(draftKb(), 'Plugins', 'make-deck'), { recursive: true }).then(() =>
+        writeFile(join(draftKb(), 'Plugins', 'make-deck', 'SKILL.md'), `---\ndescription: Decks.\n---\n\n${body}`),
+      );
+
+    beforeEach(async () => {
+      await cp(join(root, wsId), join(root, draftWsId), { recursive: true });
+      clones.add(DRAFT);
+    });
+
+    test('a skill that exists only on the branch is listed as unmerged; the released ones are not marked', async () => {
+      await writeDeck();
+      const list = await named();
+      expect(Object.keys(list).sort()).toEqual(['coding-guidelines', 'make-deck', 'rfi']);
+      expect(list['make-deck']).toMatchObject({ unmerged: true, branch: DRAFT, description: 'Decks.' });
+      // The skills the branch shares with the default branch are the released
+      // ones, read through a draft's clone: nothing about them is unapproved.
+      expect(list['rfi'].unmerged).toBeUndefined();
+      expect(list['rfi'].branch).toBeUndefined();
+      expect(list['coding-guidelines'].unmerged).toBeUndefined();
+    });
+
+    test('without a branch the draft-only skill is absent, and nothing carries a mark', async () => {
+      await writeDeck();
+      const list = await svc().listSkills(user);
+      expect(list.map((s) => s.name)).toEqual(['coding-guidelines', 'rfi']);
+      expect(list.some((s) => s.unmerged !== undefined || s.branch !== undefined)).toBe(false);
+    });
+
+    test('get_skill loads the draft-only skill, body starting with the unmerged line', async () => {
+      await writeDeck();
+      const res = await svc().getSkill(user, 'make-deck', undefined, { branch: DRAFT });
+      expect(res.ok && res.kind === 'skill').toBe(true);
+      if (!res.ok || res.kind !== 'skill') return;
+      expect(res.skill.body.split('\n')[0]).toBe(
+        `This skill is read from the unmerged branch "${DRAFT}" and is not approved.`,
+      );
+      expect(res.skill.body.split('\n')[0]).toBe(unmergedSkillNotice(DRAFT));
+      expect(res.skill.body).toContain('# Deck');
+      expect(res.skill).toMatchObject({ unmerged: true, branch: DRAFT, path: 'Plugins/make-deck' });
+      // Without the branch there is no such skill at all.
+      expect(await svc().getSkill(user, 'make-deck')).toEqual({ ok: false, error: 'not_found' });
+    });
+
+    test('a skill changed on the branch loads changed there and released without the branch', async () => {
+      await writeFile(
+        join(draftKb(), 'Plugins', 'rfi', 'SKILL.md'),
+        RFI_SKILL.replace('You answer RFIs.', 'You answer RFIs, in three paragraphs.'),
+      );
+      const service = svc();
+      const draft = await service.getSkill(user, 'rfi', undefined, { branch: DRAFT });
+      expect(draft.ok && draft.kind === 'skill' && draft.skill.body).toContain('in three paragraphs');
+      expect(draft.ok && draft.kind === 'skill' && draft.skill.body.split('\n')[0]).toBe(unmergedSkillNotice(DRAFT));
+      expect(draft.ok && draft.kind === 'skill' && draft.skill.unmerged).toBe(true);
+      expect((await named(service))['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+
+      const released = await service.getSkill(user, 'rfi');
+      expect(released.ok && released.kind === 'skill' && released.skill.body).not.toContain('three paragraphs');
+      expect(released.ok && released.kind === 'skill' && released.skill.body).not.toContain('unmerged');
+      expect(released.ok && released.kind === 'skill' && released.skill.unmerged).toBeUndefined();
+    });
+
+    test('a skill unchanged on the branch carries no mark and no line — it is the released answer', async () => {
+      const service = svc();
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DRAFT })).toEqual(
+        await service.getSkill(user, 'rfi'),
+      );
+      expect(await service.getSkill(user, 'rfi', 'scripts/build_xlsx.py', { branch: DRAFT })).toEqual(
+        await service.getSkill(user, 'rfi', 'scripts/build_xlsx.py'),
+      );
+    });
+
+    test('a bundled file changed on the branch makes the skill unmerged, and rides beside its content', async () => {
+      // The SKILL.md is byte-identical: the difference is in the folder.
+      await writeFile(join(draftKb(), 'Plugins', 'rfi', 'scripts', 'build_xlsx.py'), 'print("xlsx v2")\n');
+      expect((await named())['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+      const file = await svc().getSkill(user, 'rfi', 'scripts/build_xlsx.py', { branch: DRAFT });
+      expect(file).toEqual({
+        ok: true,
+        kind: 'file',
+        file: {
+          name: 'rfi',
+          file: 'scripts/build_xlsx.py',
+          path: 'Plugins/rfi/scripts/build_xlsx.py',
+          // The notice never goes INSIDE a script.
+          content: 'print("xlsx v2")\n',
+          unmerged: true,
+          branch: DRAFT,
+        },
+      });
+    });
+
+    test('an asset added on the branch is a difference too', async () => {
+      await writeFile(join(draftKb(), 'Plugins', 'rfi', 'scripts', 'extra.py'), 'print("new")\n');
+      expect((await named())['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+
+    test('a skill deleted on the branch is absent there and still released without it', async () => {
+      await rm(join(draftKb(), 'Plugins', 'rfi'), { recursive: true });
+      const service = svc();
+      expect(Object.keys(await named(service))).toEqual(['coding-guidelines']);
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DRAFT })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      expect((await service.listSkills(user)).map((s) => s.name)).toContain('rfi');
+    });
+
+    test("access is judged on the branch, with that branch's rules", async () => {
+      // The same caller, the same skill: readable on the default branch,
+      // denied in the draft's own workspace.
+      const perBranch: IAccessControl = {
+        canRead: async () => true,
+        canReadBatch: async (w: string, _e: string, paths: string[]) =>
+          new Map(paths.map((p) => [p, !(w === draftWsId && p.includes('/rfi/'))])),
+      } as unknown as IAccessControl;
+      const service = svc(perBranch);
+      expect(Object.keys(await named(service))).toEqual(['coding-guidelines']);
+      // Not `forbidden`: a draft skill the caller may not read there is one
+      // they must not learn exists.
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DRAFT })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      expect(await service.getSkill(user, 'rfi', 'scripts/build_xlsx.py', { branch: DRAFT })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      // The released answer is untouched by the draft's rules.
+      expect((await service.listSkills(user)).map((s) => s.name)).toContain('rfi');
+      expect((await service.getSkill(user, 'rfi')).ok).toBe(true);
+    });
+
+    test('a branch that does not exist is a 404 naming it, as on the file tools', async () => {
+      const service = svc();
+      await expect(service.listSkills(user, { branch: 'juan/typo' })).rejects.toMatchObject({
+        status: 404,
+        kind: 'branch-not-found',
+        branch: 'juan/typo',
+        message: 'There is no branch named juan/typo.',
+      });
+      await expect(service.getSkill(user, 'rfi', undefined, { branch: 'juan/typo' })).rejects.toMatchObject({
+        status: 404,
+        kind: 'branch-not-found',
+      });
+    });
+
+    test('naming the default branch answers exactly as naming nothing', async () => {
+      await writeDeck();
+      const service = svc();
+      expect(await service.listSkills(user, { branch: DEFAULT_BRANCH })).toEqual(await service.listSkills(user));
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DEFAULT_BRANCH })).toEqual(
+        await service.getSkill(user, 'rfi'),
+      );
+    });
+
+    test('a branch read is never cached: the next call sees what the agent just wrote', async () => {
+      const service = svc();
+      expect(Object.keys(await named(service))).not.toContain('make-deck');
+      await writeDeck();
+      // Same instance, no `invalidate()`: the released catalog is cached, a
+      // draft is not.
+      expect(Object.keys(await named(service))).toContain('make-deck');
+    });
+
+    // The `unmerged` verdict compares two folder digests, and the released
+    // side of that comparison is memoized per cached catalog (it used to be
+    // re-hashed once per skill per call). These two pin what the memo may and
+    // may not do.
+    test('the memo never makes a draft stale: an edit on the branch is seen on the next call', async () => {
+      const service = svc();
+      expect((await named(service))['rfi'].unmerged).toBeUndefined();
+      await writeFile(join(draftKb(), 'Plugins', 'rfi', 'scripts', 'build_xlsx.py'), 'print("on the branch")\n');
+      // Same instance, no `invalidate()`: the draft's digests are built per
+      // call along with its catalog, so the agent's own last write shows.
+      expect((await named(service))['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+
+    test('the released digests live and die with the released catalog', async () => {
+      const service = svc();
+      expect((await named(service))['rfi'].unmerged).toBeUndefined();
+      // An asset of the RELEASED copy changes. The catalog caches the file
+      // list, not the contents, so this is visible to a digest the moment one
+      // is taken — and the memo holds the pre-change one for the same TTL the
+      // rest of the released answer is held for.
+      await writeFile(join(root, wsId, KB_DIR, 'Plugins', 'rfi', 'scripts', 'build_xlsx.py'), 'print("released")\n');
+      expect((await named(service))['rfi'].unmerged).toBeUndefined();
+      service.invalidate();
+      expect((await named(service))['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+
+    test('the global set (no caller) can be read from a branch too', async () => {
+      await writeDeck();
+      const list = await svc().listSkills(undefined, { branch: DRAFT });
+      expect(list.find((s) => s.name === 'make-deck')).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+  });
 });

package/src/modules/skills/skills.contract.ts

@@ -2,7 +2,10 @@
  * Skills are reusable specialist instructions living under `Plugins/<plugin>/<name>/SKILL.md`
  * in the KB repo. Discovery/loading is pinned to the DEFAULT branch — the catalog
  * is a single global, released set (a skill on a draft isn't discoverable until
- * merged). Progressive disclosure: `listSkills` = name + description (level 1),
+ * merged) — UNLESS the caller names a branch, which reads the skills as they are
+ * on that draft and marks the ones the default branch does not have yet (see
+ * {@link ListSkillsOptions} and `unmerged` below). Progressive disclosure:
+ * `listSkills` = name + description (level 1),
  * `getSkill` = full body + bundled-file paths (level 2), `getSkill(file)` = a
  * bundled file's content (level 3).
  */
@@ -38,6 +41,17 @@ export interface SkillSummary {
    * surfaces, which load skills by name and never by plugin.
    */
   plugins?: PluginMembership[];
+  /**
+   * Set only on an answer read from a branch OTHER than the default, and only
+   * on a skill whose folder DIFFERS there: it exists only on that branch, or
+   * its content was changed on it. Nobody has approved what such a skill says
+   * — it is not merged. A skill the branch shares byte-for-byte with the
+   * default branch carries no mark, because there is nothing unapproved about
+   * it.
+   */
+  unmerged?: true;
+  /** With `unmerged`: the branch the skill was read from. */
+  branch?: string;
 }
 
 export interface Skill extends SkillSummary {
@@ -57,6 +71,15 @@ export interface SkillFileContent {
   /** Repo-root-relative path of the file. */
   path: string;
   content: string;
+  /**
+   * As on {@link SkillSummary} — the file came off a branch whose copy of this
+   * skill differs from the default branch's. A note BESIDE the content, never
+   * inside it: a bundled file is a script or a data file, and a sentence
+   * prepended to one is a syntax error rather than a warning. A skill's body,
+   * which is prose an agent reads, carries the line instead.
+   */
+  unmerged?: true;
+  branch?: string;
 }
 
 export type GetSkillResult =
@@ -64,32 +87,76 @@ export type GetSkillResult =
   | { ok: true; kind: 'file'; file: SkillFileContent }
   | { ok: false; error: 'not_found' | 'forbidden' | 'invalid_file' }
   /**
-   * A `version` was asked for that no commit of the skill's `SKILL.md` on the
-   * default branch declared. `versions` is every version the history did
-   * declare, newest first — the caller picks from those or asks for the
-   * latest by leaving `version` out.
+   * A `version` was asked for that no commit of the skill's `SKILL.md`
+   * declared in the history searched — the default branch's, or `branch`'s own
+   * when a branch was named. `versions` is every version that history did
+   * declare, newest first, so it too is that branch's answer: the caller picks
+   * from those or asks for the latest by leaving `version` out.
    */
   | { ok: false; error: 'version_not_found'; versions: string[] };
 
+/**
+ * What `listSkills` may be asked beyond a caller.
+ *
+ * The branch is the ONE thing that moves the catalog off the default branch.
+ * Omitted (or naming the default branch itself), every answer is exactly the
+ * released one — the browser menu and the MCP prompts take that path and are
+ * unaffected by this option existing.
+ */
+export interface ListSkillsOptions {
+  /**
+   * Read the skills as they are on this branch instead of the default one: a
+   * skill that exists only there is listed, one changed there is listed with
+   * its changed description and version, one deleted there is absent. Access
+   * is judged on THAT branch, with that branch's access rules. A branch the
+   * platform has never heard of is a 404 naming it, as on the file tools.
+   *
+   * Everything listed from a non-default branch that differs from the default
+   * carries `unmerged: true` and this branch name: nobody approved it.
+   */
+  branch?: string;
+}
+
 /** What `getSkill` may be asked beyond a name and a file. */
 export interface GetSkillOptions {
   /**
    * The version the skill declared in the copy to load — its
    * `metadata.version`, else a top-level `version`, else `lifecycle.version`.
    * Omitted, the skill is loaded as it is now — the latest. Given, the
-   * default branch's history of the skill's `SKILL.md` is searched newest
-   * first for the most recent commit that declared exactly this version, and
-   * the skill (body, bundled files, or the one `file` asked for) is served as
-   * it was at that commit. Read access is the caller's access to the skill as
-   * it is now: a skill you may read, you may read the history of.
+   * history of the skill's `SKILL.md` is searched newest first for the most
+   * recent commit that declared exactly this version, and the skill (body,
+   * bundled files, or the one `file` asked for) is served as it was at that
+   * commit. Read access is the caller's access to the skill as it is now: a
+   * skill you may read, you may read the history of.
+   *
+   * The history searched is the one belonging to the branch being read: the
+   * default branch's, or — with `branch` — that branch's own, including the
+   * `versions` a `version_not_found` lists.
    */
   version?: string;
+  /**
+   * Load the skill as it is on this branch instead of the default one — see
+   * {@link ListSkillsOptions.branch}, which it mirrors exactly: same branch
+   * resolution, same 404, same access rules read on that branch. When the
+   * skill differs from the default branch's copy, the body returned BEGINS
+   * with one line saying so (a bundled file carries `unmerged` beside its
+   * content instead).
+   *
+   * With `version`, the history searched is that branch's own. The agent
+   * tools refuse the two together rather than make a caller reason about which
+   * branch a version came from; this service answers both, because the
+   * combination has exactly one sensible meaning.
+   */
+  branch?: string;
 }
 
 /**
- * The slice of git the skill service reads history through — the default
- * branch's own clone, never a caller's draft. Narrow on purpose: the catalog
- * is a disk scan and needs none of this; only a `version` asks for history.
+ * The slice of git the skill service reads history through. Every call names
+ * the workspace to read in, which is always the clone the skill itself was
+ * scanned out of — the default branch's, or the draft a `branch` named, so a
+ * version asked for on a branch is answered from that branch's history.
+ * Narrow on purpose: the catalog is a disk scan and needs none of this; only
+ * a `version` asks for history.
  */
 export interface SkillHistorySource {
   /** The commits (newest first) on `ref` that touched `repoRelativePath`, at most `limit`. */
@@ -133,17 +200,23 @@ export interface IPendingSkillService {
 
 export interface ISkillService {
   /**
-   * The default-branch skill catalog. When `userEmail` is given, filtered to
-   * skills that user may read (`canRead`); omit it for the global set (used to
-   * compose the tool descriptions in the manual).
+   * The default-branch skill catalog — or `options.branch`'s, when one is
+   * named. When `userEmail` is given, filtered to skills that user may read
+   * (`canRead`, judged on the branch being read); omit it for the global set
+   * (used to compose the tool descriptions in the manual, which always
+   * describe the default branch).
    */
-  listSkills(userEmail?: string): Promise<SkillSummary[]>;
+  listSkills(userEmail?: string, options?: ListSkillsOptions): Promise<SkillSummary[]>;
   /**
    * Load a skill's body (+ files), or a bundled file's content when `file` is
    * given — as it is now, or as it was at the commit that declared
    * `options.version` (see {@link GetSkillOptions}).
    */
   getSkill(userEmail: string, name: string, file?: string, options?: GetSkillOptions): Promise<GetSkillResult>;
-  /** Drop the cached catalog (call after a merge to the default branch). */
+  /**
+   * Drop the cached DEFAULT-branch catalog (call after a merge to it). A
+   * branch read is never cached, so an agent that writes a skill on its draft
+   * and lists it right after sees what it just wrote.
+   */
   invalidate(): void;
 }