@bevel-software/platform-core-backend 0.14.0 → 0.19.0

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

@@ -0,0 +1,203 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('skills');
+import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import {
+  DEFAULT_BRANCH,
+  joinBranchFor,
+  type AuthUser,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { spliceGrant } from '../access-model/access-splice.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { JoinRequestsService } from '../plugins/join-requests.service.js';
+import type { ISkillService } from './skills.contract.js';
+
+/**
+ * Asking for WRITE on a shared skill — the same machinery as asking to join a
+ * plugin, pointed at a skill folder instead of a plugin folder.
+ *
+ *   POST /api/skills/:name/access-request               → { ok, number }
+ *   GET  /api/skills/:name/access-requests              → { requests }   (skill editors)
+ *   POST /api/skills/:name/access-requests/:n/reconcile → { closed }
+ *
+ * Why it exists: linking a skill into a plugin needs write on the skill's
+ * rules (the link grants the plugin's principal there), and a plugin manager
+ * often has no say over a skill some other scope owns. The request is a plain
+ * change request whose branch splices `write: <requester>` into the skill
+ * folder's `access.md`; the skill's editors see its proposals and accept
+ * through the ordinary grant path, and it retires itself once the default
+ * branch carries the grant (`JoinRequestsService`, keyed on the skill FOLDER
+ * path rather than a plugin name — the branch-name convention takes any
+ * exact string).
+ *
+ * Fail-closed like the skill catalog: a skill the caller cannot read answers
+ * as unknown, and the editors' listing answers `[]` to anyone else.
+ */
+export function createSkillAccessRequestRoutes(deps: {
+  skillService: ISkillService;
+  accessControl: IAccessControl;
+  workflow: IWorkflowService;
+  workspaceService: WorkspaceService;
+  joinRequests: JoinRequestsService;
+  kbDirName: string;
+  resolveUser: (req: express.Request) => Promise<AuthUser | null>;
+}): express.Router {
+  const { skillService, accessControl, workflow, workspaceService, joinRequests, kbDirName, resolveUser } = deps;
+  const router = express.Router();
+  const wsId = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const rulesOf = (folder: string) => `${folder}/access.md`;
+
+  /** The skill the caller may read, by name — or null after answering 404. */
+  async function readableSkill(
+    req: express.Request,
+    res: express.Response,
+  ): Promise<{ user: AuthUser; folder: string; name: string } | null> {
+    const user = await resolveUser(req);
+    if (!user) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return null;
+    }
+    const name = String(req.params.name);
+    const skill = (await skillService.listSkills(user.email)).find((s) => s.name === name);
+    if (!skill) {
+      res.status(404).json({ error: 'Unknown skill', kind: 'unknown-skill' });
+      return null;
+    }
+    return { user, folder: skill.path, name };
+  }
+
+  router.post('/skills/:name/access-request', async (req, res) => {
+    try {
+      const ctx = await readableSkill(req, res);
+      if (!ctx) return;
+      const { user, folder, name } = ctx;
+      if (await accessControl.canWrite(wsId(), user.email, rulesOf(folder))) {
+        res.status(409).json({ error: 'You can already edit this skill', kind: 'already-writable' });
+        return;
+      }
+      const branch = joinBranchFor(user.email, folder);
+      // FRESH: a repeated click must find the request the previous one opened,
+      // and the cached listing can trail it — a miss here would send the
+      // retry into a duplicate refusal.
+      const existing = (await workflow.listChangeRequestsAuthoredBy(user.email, { fresh: true })).find(
+        (cr) => cr.state === 'open' && cr.branch === branch,
+      );
+      if (existing) {
+        res.json({ ok: true, number: existing.number });
+        return;
+      }
+      // The branch may already exist (a request listed as closed, a retry
+      // after a failed open). Existence is PROBED, before and — if creation
+      // fails — after: the race shows up as "already exists" locally or as a
+      // rejected push when origin got there first, and a message is not a
+      // contract. A branch that is there is proceeded against; anything else
+      // is a real failure, and a proposal on a branch that was not made would
+      // be worse than the error. STRICT: the list proves absence, and a
+      // listing that could not fetch proves nothing — it throws instead of
+      // serving refs from before the branch was made (or deleted).
+      const branchExists = async () =>
+        (await workflow.listBranches(wsId(), { freshFetch: true, strictFetch: true })).some(
+          (b) => b.name === branch,
+        );
+      if (!(await branchExists())) {
+        try {
+          await workflow.createBranch(wsId(), branch, DEFAULT_BRANCH);
+        } catch (err) {
+          if (!(await branchExists())) throw err;
+        }
+      }
+      const ws = await workspaceService.getOrCreateForBranch(branch);
+      const accessPath = `${kbDirName}/${rulesOf(folder)}`;
+      // Only a PROVEN absence reads as "no rules yet": any other failure must
+      // not be turned into an empty file that a splice then overwrites.
+      const current = await workspaceService.readFile(ws.id, accessPath).catch((err: unknown) => {
+        if (!isAbsence(err)) throw err;
+        return '';
+      });
+      const spliced = spliceGrant(
+        current,
+        'write',
+        { 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 write access to ${name}`);
+      }
+      const detail = await workflow.openChangeRequest(ws.id, user, {
+        sourceBranch: branch,
+        targetBranch: DEFAULT_BRANCH,
+        title: `Access request: ${name}`,
+        description:
+          `${user.name} asked to edit the skill ${name}. An editor of the skill 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(domainErrorBody(err));
+        return;
+      }
+      log.error('failed to open an access request:', { err });
+      res.status(500).json({ error: 'Failed to request access' });
+    }
+  });
+
+  /** The caller as an EDITOR of the skill's rules, or null after answering. */
+  async function requireEditor(
+    req: express.Request,
+    res: express.Response,
+    onDenied: () => void,
+  ): Promise<{ user: AuthUser; folder: string } | null> {
+    const ctx = await readableSkill(req, res);
+    if (!ctx) return null;
+    if (!(await accessControl.canWrite(wsId(), ctx.user.email, rulesOf(ctx.folder)))) {
+      onDenied();
+      return null;
+    }
+    return ctx;
+  }
+
+  router.get('/skills/:name/access-requests', async (req, res) => {
+    try {
+      const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
+      if (!ctx) return;
+      const crs = await workflow.listChangeRequests();
+      res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
+    } catch (err) {
+      log.error('failed to list access requests:', { err });
+      res.status(500).json({ error: 'Failed to list access requests' });
+    }
+  });
+
+  router.post('/skills/:name/access-requests/:number/reconcile', async (req, res) => {
+    try {
+      const ctx = await requireEditor(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.folder, ctx.folder, cr, ctx.user) });
+    } catch (err) {
+      log.error('failed to reconcile an access request:', { err });
+      res.status(500).json({ error: 'Failed to reconcile the request' });
+    }
+  });
+
+  return router;
+}

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

@@ -7,6 +7,24 @@
  * bundled file's content (level 3).
  */
 
+/**
+ * One plugin a skill belongs to — by sitting INSIDE the plugin folder
+ * (`linked: false`) or by being LINKED from the plugin's manifest
+ * (`linked: true`). For a link, `granted` is the link's HEALTH: whether the
+ * plugin's members can read the skill through it. For a link this platform
+ * manages that is whether the skill's own access rules name the plugin's
+ * `plugin/<Name>/read` principal — the link service writes that grant with
+ * the link, so `false` means a hand edit took it away. A link read from an
+ * external plugin format needs no grant (the skill's own scope decides who
+ * reads it) and is always `true`; the flag never proves a principal exists.
+ */
+export interface PluginMembership {
+  /** The plugin folder name. */
+  name: string;
+  linked: boolean;
+  granted: boolean;
+}
+
 export interface SkillSummary {
   /** Canonical id = the skill's folder name (e.g. `rfi`). */
   name: string;
@@ -14,6 +32,12 @@ export interface SkillSummary {
   version?: string;
   /** Repo-root-relative skill folder, e.g. `Plugins/Everyone/rfi`. */
   path: string;
+  /**
+   * The plugins this skill belongs to, decorated onto the catalog by the
+   * browser route (the catalog itself is plugin-unaware). Absent on the agent
+   * surfaces, which load skills by name and never by plugin.
+   */
+  plugins?: PluginMembership[];
 }
 
 export interface Skill extends SkillSummary {
@@ -38,7 +62,43 @@ export interface SkillFileContent {
 export type GetSkillResult =
   | { ok: true; kind: 'skill'; skill: Skill }
   | { ok: true; kind: 'file'; file: SkillFileContent }
-  | { ok: false; error: 'not_found' | 'forbidden' | 'invalid_file' };
+  | { 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.
+   */
+  | { ok: false; error: 'version_not_found'; versions: 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.
+   */
+  version?: 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.
+ */
+export interface SkillHistorySource {
+  /** The commits (newest first) on `ref` that touched `repoRelativePath`, at most `limit`. */
+  pathHistory(workspaceId: string, ref: string, repoRelativePath: string, limit: number): Promise<string[]>;
+  /** The file's content at `ref`, or null when it is not there at that ref. */
+  readFileAtRef(workspaceId: string, ref: string, repoRelativePath: string): Promise<string | null>;
+  /** Every file under `folder` at `ref`, repo-root-relative. */
+  listFilesAtRef(workspaceId: string, ref: string, folder: string): Promise<string[]>;
+}
 
 /**
  * A skill that exists ONLY on an open change request's branch — proposed, not
@@ -78,8 +138,12 @@ export interface ISkillService {
    * compose the tool descriptions in the manual).
    */
   listSkills(userEmail?: string): Promise<SkillSummary[]>;
-  /** Load a skill's body (+ files), or a bundled file's content when `file` is given. */
-  getSkill(userEmail: string, name: string, file?: string): Promise<GetSkillResult>;
+  /**
+   * 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). */
   invalidate(): void;
 }

package/src/modules/skills/skills.routes.ts

@@ -1,6 +1,22 @@
 import express from 'express';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import type { IPendingSkillService, ISkillService } from './skills.contract.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { IPendingSkillService, ISkillService, PluginMembership } from './skills.contract.js';
+import type { IAllowedToolsChecker } from './allowed-tools-check.js';
+
+/** The slice of the plugin link index this surface reads — see `PluginLinkIndex`. */
+export interface SkillMembershipSource {
+  membership(): Promise<{
+    bySkill: Map<string, PluginMembership[]>;
+    byPlugin: Map<string, { folder: string }>;
+  }>;
+}
+
+/** The one access verdict this surface needs: may the caller read a path on the default branch? */
+export interface SkillMembershipGate {
+  canReadBatch(workspaceId: string, userEmail: string, paths: string[]): Promise<Map<string, boolean>>;
+}
 
 /**
  * Browser-facing (JWT) skill routes for the `/`-command menu, mounted behind
@@ -8,14 +24,33 @@ import type { IPendingSkillService, ISkillService } from './skills.contract.js';
  * so discovery, default-branch pinning, and per-user `canRead` filtering live
  * ONCE — the frontend never re-implements skill discovery or bypasses access.
  *
- *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user)
+ *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user,
+ *                                                              each with its `plugins`)
  *   GET /api/skills/pending    → { skills: PendingSkill[] }   (proposed, not released)
  *   GET /api/skills/:name      → GetSkillResult               (body + files)
  *   GET /api/skills/:name?file=… → GetSkillResult             (a bundled file's content)
+ *
+ * `plugins` is decorated HERE, not in the catalog: the catalog is what agents
+ * load by name and it stays plugin-unaware; the browser is the surface that
+ * groups skills by plugin. Optional dependency, so a host without the link
+ * index gets undecorated summaries rather than a 500.
  */
 export function createSkillsRoutes(
   skillService: ISkillService,
   pendingSkills?: IPendingSkillService,
+  links?: SkillMembershipSource,
+  /**
+   * With `links`: the memberships a caller sees name only plugins they may
+   * DISCOVER (read the plugin's access.md — the plugin index's own listing
+   * verdict), so this surface never reveals a plugin `/api/plugins` omits.
+   */
+  gate?: SkillMembershipGate,
+  /**
+   * When given, a loaded skill carries `warnings` for `allowed-tools` entries
+   * that name no tool the caller can see — the same list `get_skill` returns,
+   * so the skill page can say so when it opens, not only after a save.
+   */
+  allowedTools?: IAllowedToolsChecker,
 ): express.Router {
   const router = express.Router();
 
@@ -25,7 +60,35 @@ export function createSkillsRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
-    res.json({ skills: await skillService.listSkills(email) });
+    const skills = await skillService.listSkills(email);
+    if (!links) {
+      res.json({ skills });
+      return;
+    }
+    let bySkill: Map<string, PluginMembership[]>;
+    // Fail closed: memberships without a gate to judge them by name nothing.
+    let discoverable: (plugin: string) => boolean = () => false;
+    try {
+      const membership = await links.membership();
+      bySkill = membership.bySkill;
+      if (gate) {
+        const folders = [...membership.byPlugin.entries()];
+        const verdicts = folders.length
+          ? await gate.canReadBatch(
+              workspaceIdForBranch(DEFAULT_BRANCH),
+              email,
+              folders.map(([, p]) => `${p.folder}/access.md`),
+            )
+          : new Map<string, boolean>();
+        const visible = new Set(folders.filter(([, p]) => verdicts.get(`${p.folder}/access.md`) === true).map(([name]) => name));
+        discoverable = (plugin) => visible.has(plugin);
+      }
+    } catch {
+      bySkill = new Map(); // membership is a decoration; the shelf must not fall with it
+    }
+    res.json({
+      skills: skills.map((s) => ({ ...s, plugins: (bySkill.get(s.path) ?? []).filter((m) => discoverable(m.name)) })),
+    });
   });
 
   /**
@@ -52,7 +115,15 @@ export function createSkillsRoutes(
       return;
     }
     const file = typeof req.query.file === 'string' ? req.query.file : undefined;
-    res.json(await skillService.getSkill(email, req.params.name, file));
+    // `?version=` loads the skill as it was at the commit that declared that
+    // version — the same option the agent tool takes.
+    const version = typeof req.query.version === 'string' ? req.query.version : undefined;
+    const result = await skillService.getSkill(email, req.params.name, file, { version });
+    if (!allowedTools || !result.ok || result.kind !== 'skill') {
+      res.json(result);
+      return;
+    }
+    res.json({ ...result, warnings: await allowedTools.check(email, result.skill.allowedTools) });
   });
 
   return router;