@bevel-software/platform-core-backend 0.15.1 → 0.20.0

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

@@ -1,17 +1,14 @@
 import {
-  DEFAULT_BRANCH,
   PLUGINS_DIR,
   SKILLS_DIR,
-  type ChangeRequest,
-  type IWorkflowService,
 } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { hashEmail } from '../../shared/hash-email.js';
 import { resolveDeclaredId } from '../../shared/frontmatter-id.js';
+import { visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { isSafeSkillName, parseSkillFrontmatter } from './skills.service.js';
 import type { IPendingSkillService, ISkillService, PendingSkill } from './skills.contract.js';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
 
 const SKILL_DOC = 'SKILL.md';
 
@@ -27,14 +24,11 @@ const SKILL_DOC = 'SKILL.md';
  * rather than a widening of the catalog — an unapproved skill must never become
  * loadable just because it became visible.
  *
- * WHO MAY SEE ONE is narrower than who may see the catalog: the author, and
- * whoever could approve it. "Could approve it" is not re-stated here as a
- * plugin-admin check — it is `canWrite` on the SKILL.md the request would
- * create. The new folder carries no `access.md` of its own, so that verdict
- * inherits from the plugin folder, which IS the plugin's admin; asking the access
- * tree keeps this surface and the merge gate answering with one voice, and it
- * keeps working for skills nested in a category subfolder that carries rules of
- * its own.
+ * WHO MAY SEE ONE, and how a proposal is read at its own branch, live in
+ * `shared/pending-proposals.ts` — shared with the tool surface, which is the
+ * same shape for the same reasons. What stays here is what is specific to a
+ * skill: which touched paths are a skill of their own, and how a SKILL.md
+ * names itself.
  *
  * Everything degrades to "nothing pending" rather than throwing: this hangs off
  * the library's list load, and a review surface that cannot answer must not
@@ -49,17 +43,6 @@ export class PendingSkillsService implements IPendingSkillService {
   ) {}
 
   async listPendingSkills(userEmail: string): Promise<PendingSkill[]> {
-    const email = userEmail.trim().toLowerCase();
-    if (!email) return [];
-
-    let crs: ChangeRequest[];
-    try {
-      crs = (await this.workflow.listChangeRequests()).filter((c) => c.state === 'open');
-    } catch {
-      return [];
-    }
-    if (crs.length === 0) return [];
-
     // The released set, UNFILTERED by the caller's read access. A skill someone
     // else can read and this caller cannot is still released — counting it as
     // pending would invent a review that is not happening, and would leak the
@@ -71,82 +54,38 @@ export class PendingSkillsService implements IPendingSkillService {
       return [];
     }
 
-    const candidates = crs.flatMap((cr) =>
-      cr.touchedNodePaths
-        .filter((p) => isSkillDoc(p) && !released.has(folderOf(p)))
-        .map((p) => ({ cr, docPath: p, folder: folderOf(p) })),
+    const proposed = await visibleProposedFiles(
+      {
+        workspaceService: this.workspaceService,
+        accessControl: this.accessControl,
+        workflow: this.workflow,
+      },
+      userEmail,
+      (p) => isSkillDoc(p) && !released.has(folderOf(p)),
     );
-    if (candidates.length === 0) return [];
-
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
-    const authorHash = hashEmail(email);
-
-    // One access load for every candidate. Resolved on the DEFAULT branch —
-    // the tree as it stands is what says who owns the plugin the skill is
-    // arriving into; the branch's own copy is written by the proposer and must
-    // not get a say in who reviews them.
-    const writable = await this.accessControl
-      .canWriteBatch(
-        wsId,
-        email,
-        candidates.map((c) => c.docPath),
-      )
-      .catch(() => new Map<string, boolean>());
-
-    // The branch copies are read through the default branch's clone at
-    // `origin/<branch>`, so a proposal never needs a clone of its own. Refresh
-    // first, best-effort: a request pushed seconds ago is worth one fetch, and
-    // a failed fetch should degrade to "read what we have".
-    await this.workspaceService.ensureRemotesFetched(wsId).catch(() => undefined);
 
-    const out: PendingSkill[] = [];
-    for (const { cr, docPath, folder } of candidates) {
-      const isAuthor = !!cr.authorId && cr.authorId === authorHash;
-      // Fail closed, matching the catalog: only an explicit `true` admits a
-      // reviewer. A missing entry (the batch skipped the path, the tree could
-      // not be read) means denied, never shown.
-      if (!isAuthor && writable.get(docPath) !== true) continue;
-
-      const raw = await this.readAt(wsId, cr.branch, docPath);
-      // Nothing to describe: the request touched the path but the file is gone
-      // at its head (proposed then withdrawn within the branch), or unreadable.
-      if (raw === null) continue;
-
-      const fm = parseSkillFrontmatter(raw);
+    const out: PendingSkill[] = proposed.map(({ cr, path, content, isAuthor }) => {
+      const folder = folderOf(path);
+      const fm = parseSkillFrontmatter(content);
       const folderName = folder.split('/').pop() ?? folder;
       const declared = resolveDeclaredId(fm.frontmatter, folderName);
-      out.push({
+      return {
         name: isSafeSkillName(declared) ? declared : folderName,
         description: fm.description,
         version: fm.version,
-        owner: fm.owner,
-        lifecycle: fm.lifecycle,
         path: folder,
         changeRequestNumber: cr.number,
         branch: cr.branch,
         authorName: cr.appAuthor?.name ?? cr.author.name ?? 'Someone',
         createdAt: cr.createdAt,
         isAuthor,
-      });
-    }
+      };
+    });
     // Oldest first — the one that has been waiting longest is the one that
     // needs answering, and a list that reorders as requests arrive moves under
     // the pointer.
     return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
-
-  /** The file at a branch, or null when it is absent/unreadable there. */
-  private async readAt(
-    wsId: string,
-    branch: string,
-    repoRelPath: string,
-  ): Promise<string | null> {
-    try {
-      return await this.workspaceService.readFileAtRef(wsId, `origin/${branch}`, repoRelPath);
-    } catch {
-      return null;
-    }
-  }
 }
 
 /**

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

@@ -1,4 +1,7 @@
 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,
@@ -9,6 +12,8 @@ import {
 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';
@@ -113,8 +118,7 @@ export function createSkillAccessRequestRoutes(deps: {
       // 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) => {
-        const code = (err as { code?: unknown } | null)?.code;
-        if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+        if (!isAbsence(err)) throw err;
         return '';
       });
       const spliced = spliceGrant(
@@ -139,10 +143,10 @@ export function createSkillAccessRequestRoutes(deps: {
       res.json({ ok: true, number: detail.number });
     } catch (err) {
       if (err instanceof WorkflowDomainError) {
-        res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+        res.status(err.status).json(domainErrorBody(err));
         return;
       }
-      console.error('[skills] failed to open an access request:', err);
+      log.error('failed to open an access request:', { err });
       res.status(500).json({ error: 'Failed to request access' });
     }
   });
@@ -169,7 +173,7 @@ export function createSkillAccessRequestRoutes(deps: {
       const crs = await workflow.listChangeRequests();
       res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
     } catch (err) {
-      console.error('[skills] failed to list access requests:', err);
+      log.error('failed to list access requests:', { err });
       res.status(500).json({ error: 'Failed to list access requests' });
     }
   });
@@ -190,7 +194,7 @@ export function createSkillAccessRequestRoutes(deps: {
       }
       res.json({ closed: await joinRequests.reconcile(ctx.folder, ctx.folder, cr, ctx.user) });
     } catch (err) {
-      console.error('[skills] failed to reconcile an access request:', err);
+      log.error('failed to reconcile an access request:', { err });
       res.status(500).json({ error: 'Failed to reconcile the request' });
     }
   });

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

@@ -30,14 +30,6 @@ export interface SkillSummary {
   name: string;
   description: string;
   version?: string;
-  /** The governance owner from `metadata.owner`, when the skill declares one. */
-  owner?: string;
-  /**
-   * The governance lifecycle from `metadata.lifecycle`, lowercased — `active`
-   * (or absent), `deprecated` (still served, flagged), `retired` (served to the
-   * catalog for its owners, never compiled into a distribution).
-   */
-  lifecycle?: string;
   /** Repo-root-relative skill folder, e.g. `Plugins/Everyone/rfi`. */
   path: string;
   /**
@@ -70,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
@@ -110,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

@@ -3,6 +3,7 @@ import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
 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 {
@@ -44,6 +45,12 @@ export function createSkillsRoutes(
    * 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();
 
@@ -108,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;