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

package/src/modules/plugins/plugins.service.ts

@@ -1,7 +1,13 @@
+import fs from 'node:fs/promises';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('plugins');
 import path from 'node:path';
 import {
   DEFAULT_BRANCH,
 } from '@bevel-software/platform-shared';
+import { isPrivateAccessMd } from '../access-model/access-grammar.js';
+import { isAbsence } from '../../shared/fs.contract.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -11,10 +17,19 @@ import { TtlCache } from '../../shared/ttl-cache.js';
 import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
 import type { PluginLinkIndex } from './plugin-links.js';
 import type { PluginSource } from './discovery/plugin-source.js';
-import { KbPluginSource } from './discovery/kb-plugin-source.js';
 
 const CACHE_TTL_MS = 60_000;
 
+/** What one discovery pass keeps about a plugin, before the counts and verdicts. */
+interface ScannedPlugin {
+  folders: string[];
+  /** The roots it links skills from — see `PluginSummary.linkedRoots`. */
+  linkedRoots: string[];
+  linksAreManaged: boolean;
+  displayName: string;
+  warnings: string[];
+}
+
 /**
  * The plugin index: every plugin folder in the default-branch KB, with its
  * caller-independent totals and access principals.
@@ -49,6 +64,8 @@ export class PluginIndexService implements IPluginIndexService {
     private readonly skillService: ISkillService,
     private readonly toolManualService: IToolManualService,
     private readonly kbDirName: string,
+    /** Where plugins come from — the one discovery every catalog shares. */
+    private readonly source: PluginSource,
     now: () => number = Date.now,
     /**
      * The link index, when the deployment has one: a plugin's skill count is
@@ -56,8 +73,6 @@ export class PluginIndexService implements IPluginIndexService {
      * set (and older tests) keep the inline-only count.
      */
     private readonly links?: PluginLinkIndex,
-    /** Where plugins come from — native manifests unless a dialect is configured. */
-    private readonly source: PluginSource = new KbPluginSource(),
   ) {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
@@ -109,22 +124,24 @@ export class PluginIndexService implements IPluginIndexService {
 
       const [{ skillCounts, brokenLinkCounts }, toolCounts] = await Promise.all([
         this.countThroughLinks(folders),
-        this.countTools(folders),
+        this.countTools(scanned),
       ]);
 
       const entries: PluginCatalogEntry[] = [];
       for (const [name, pluginFolders] of folders) {
         // One folder, one access boundary — the folder IS the plugin.
         const [primary] = pluginFolders;
-        const [owners, writers, readers] = await Promise.all([
+        const [owners, writers, readers, isPrivate] = await Promise.all([
           this.accessControl.eligibleOwners(wsId, primary),
           this.accessControl.eligibleWriters(wsId, primary),
           this.accessControl.eligibleReaders(wsId, primary),
+          this.readsAsPrivate(path.join(kbRoot, primary, 'access.md')),
         ]);
         entries.push({
           name,
           displayName: scanned.get(name)?.displayName ?? name,
           folders: pluginFolders,
+          linkedRoots: scanned.get(name)?.linkedRoots ?? [],
           linksAreManaged: scanned.get(name)?.linksAreManaged ?? false,
           skillCount: skillCounts.get(name) ?? 0,
           toolCount: toolCounts.get(name) ?? 0,
@@ -132,13 +149,13 @@ export class PluginIndexService implements IPluginIndexService {
           owners,
           writers,
           readers,
+          isPrivate,
+          warnings: scanned.get(name)?.warnings ?? [],
         });
       }
       return entries.sort((a, b) => a.name.localeCompare(b.name));
     } catch (err) {
-      console.warn(
-        `[plugins] plugin index unavailable: ${err instanceof Error ? err.message : String(err)}`,
-      );
+      log.warn(`plugin index unavailable: ${err instanceof Error ? err.message : String(err)}`);
       return null;
     }
   }
@@ -151,18 +168,24 @@ export class PluginIndexService implements IPluginIndexService {
    * source's existence rule (see `DiscoveredPlugin`) — for native plugins,
    * the `access.md` the class doc describes.
    */
-  private async scanFolders(
-    kbRoot: string,
-  ): Promise<Map<string, { folders: string[]; linksAreManaged: boolean; displayName: string }>> {
-    const byName = new Map<string, { folders: string[]; linksAreManaged: boolean; displayName: string }>();
+  private async scanFolders(kbRoot: string): Promise<Map<string, ScannedPlugin>> {
+    const byName = new Map<string, ScannedPlugin>();
     const discovered = await this.source.discover(kbRoot);
-    for (const w of discovered.warnings) console.warn(`[plugins] ${w}`);
+    for (const w of discovered.warnings) log.warn(w);
     for (const plugin of discovered.plugins) {
       if (plugin.personal || !plugin.exists) continue;
       byName.set(plugin.name, {
         folders: [plugin.folder],
+        linkedRoots: plugin.linkedRoots,
         linksAreManaged: plugin.linksAreManaged,
         displayName: plugin.displayName,
+        // Discovery prefixes what it says about one plugin with that
+        // plugin's folder; the page names the plugin already, so the
+        // prefix goes. Whatever names no folder (an unreadable registry)
+        // stays in the log alone.
+        warnings: discovered.warnings
+          .filter((w) => w.startsWith(`${plugin.folder}: `) || w.startsWith(`${plugin.folder}/`))
+          .map((w) => w.slice(plugin.folder.length).replace(/^[:/]\s*/, '')),
       });
     }
     return byName;
@@ -211,17 +234,55 @@ export class PluginIndexService implements IPluginIndexService {
    * prefix against the discovered folders, not by `pluginOfPath`'s
    * second-segment rule, so a dialect plugin nested three folders deep still
    * counts the servers its bundle expands.
+   *
+   * And to every plugin one of whose LINKED ROOTS holds them. A root is a
+   * skill folder or a folder of skills, and a `.tool` manual sitting beside
+   * those skills reaches the plugin the same way they do — the plugin's page
+   * lists it, so the plugin's total has to count it. Once per plugin: a root
+   * inside the plugin's own folder says nothing the folder did not say first.
+   *
+   * Without a link index, inline only — the same degradation `countThroughLinks`
+   * makes for skills. A host that composes no link index has asked for totals
+   * that count what each plugin's folder holds, and a catalog that counted a
+   * plugin's linked tools while leaving its linked skills out would describe a
+   * plugin that exists nowhere.
    */
-  private async countTools(folders: Map<string, string[]>): Promise<Map<string, number>> {
+  private async countTools(scanned: Map<string, ScannedPlugin>): Promise<Map<string, number>> {
     const counts = new Map<string, number>();
-    const byFolder = [...folders.entries()].map(([name, [folder]]) => ({ name, prefix: `${folder}/` }));
+    const plugins = [...scanned].map(([name, p]) => ({
+      name,
+      folders: p.folders,
+      roots: this.links ? p.linkedRoots : [],
+    }));
+    const bump = (name: string) => counts.set(name, (counts.get(name) ?? 0) + 1);
     for (const tool of await this.toolManualService.listAllSummaries()) {
-      const owner = byFolder.find((f) => tool.path.startsWith(f.prefix));
-      if (!owner) continue;
-      counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
+      const inline = plugins.find((p) => p.folders.some((f) => tool.path.startsWith(`${f}/`)));
+      if (inline) bump(inline.name);
+      for (const p of plugins) {
+        if (p === inline) continue;
+        if (p.roots.some((root) => tool.path.startsWith(`${root}/`))) bump(p.name);
+      }
     }
     return counts;
   }
+
+  /**
+   * What the plugin's own access.md says of itself — see
+   * `PluginCatalogEntry.isPrivate`. Read from disk rather than through the
+   * resolver: the mark reflects the file's frontmatter as written. An
+   * ABSENT file makes no statement (false: a plugin discovered by its
+   * manifest may have no rules yet); any other failure to read it is a real
+   * one and propagates, so the catalog never claims a privacy verdict it
+   * could not inspect — `build` degrades the whole read, as for any fault.
+   */
+  private async readsAsPrivate(accessMdPath: string): Promise<boolean> {
+    try {
+      return isPrivateAccessMd(await fs.readFile(accessMdPath, 'utf8'));
+    } catch (err) {
+      if (isAbsence(err)) return false;
+      throw err;
+    }
+  }
 }
 
 /**
@@ -244,3 +305,16 @@ function bucketByFolder(items: { path: string }[], folders: Map<string, string[]
 export function pluginsWorkspaceId(): string {
   return workspaceIdForBranch(DEFAULT_BRANCH);
 }
+
+/**
+ * A plugin folder's path BELOW the plugins root: `GTM`, or `teams/deep`.
+ *
+ * The key a join request is cut by — its branch, and the row that records it
+ * — so it lives here rather than in any one of the three places that need to
+ * compute it. The whole path, not the basename, so two plugins whose folders
+ * share a basename can never share a branch; and it survives a rename of the
+ * plugin's identity, which moves no folder.
+ */
+export function pluginFolderBelowRoot(folder: string): string {
+  return folder.slice(folder.indexOf('/') + 1);
+}

package/src/modules/plugins/plugins.tools.ts

@@ -0,0 +1,88 @@
+import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+
+/**
+ * The two plugin tools an agent has, both surfaces — DESCRIPTIONS of the
+ * app's own creation endpoints, not a second implementation of them:
+ *
+ *  - `my_plugin`     → `POST /api/plugins/personal`
+ *  - `create_plugin` → `POST /api/plugins`
+ *
+ * The endpoints are the same ones the New plugin button and the first-visit
+ * personal-folder ensure call; they sit behind a gate that admits an agent's
+ * connection key as well as a session (`keyOrSessionAuth`), so one route
+ * serves both. Without these an agent asked to "put my skills in Hexis" had
+ * nowhere to write: the personal folder is created lazily by the web app
+ * under a name derived from the user's id, and a non-admin's plain write
+ * under the plugins root is refused by the root rules.
+ *
+ * Every rule the app enforces — names, reserved prefixes, twins, where a
+ * plugin may go, the one commit — is the endpoint's, so it holds for an
+ * agent exactly as for a person; a refusal comes back as the endpoint's own
+ * 4xx with its message.
+ */
+export function registerPluginsTools(registry: IToolRegistry): void {
+  registry.registerExternalTool(MY_PLUGIN);
+  registry.registerInternalTool(MY_PLUGIN);
+  registry.registerExternalTool(CREATE_PLUGIN);
+  registry.registerInternalTool(CREATE_PLUGIN);
+}
+
+/** The endpoint's answer, `ProvisionedPlugin` — see `PluginProvisionService`. */
+const PROVISIONED_OUTPUT = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: 'The plugin folder, repo-relative (e.g. `Plugins/personal-abc`, `Plugins/Teams/GTM`) — the path the file tools address.' },
+    skillsDir: { type: 'string', description: 'Where its skills go: `<path>/skills`. Each skill is a subfolder holding a `SKILL.md`.' },
+    folder: { type: 'string', description: 'The same folder as its path below the plugins root.' },
+    name: { type: 'string', description: 'The plugin identity (its manifest name), as grants and the marketplace spell it.' },
+    displayName: { type: 'string', description: 'What people see it called — the manifest `displayName`, exactly as persisted: for `create_plugin`, the name that was asked for, trimmed; for `my_plugin`, the personal folder\'s own label.' },
+    created: { type: 'boolean', description: 'False when the folder already existed.' },
+  },
+} as const;
+
+export const MY_PLUGIN: UtcpTool = toolDef({
+  name: 'my_plugin',
+  description:
+    "The caller's own private plugin — their personal space in the knowledge base, created on first use. " +
+    'Returns its folder and where skills go inside it (`skillsDir`); write a skill there as ' +
+    '`<skillsDir>/<skill-name>/SKILL.md` with the file tools, opening with the Agent Skills frontmatter ' +
+    '(`name`, `description`, and `metadata.version` such as `"1.0.0"`). Readable only by its owner — not even admins — and ' +
+    'never listed as a shared plugin. Idempotent: calling it again returns the same folder.',
+  path: '/api/plugins/personal',
+  inputs: { type: 'object', properties: {}, additionalProperties: false },
+  outputs: PROVISIONED_OUTPUT,
+  // `write`: both make folders and commit — a read-scoped caller's manual
+  // must not advertise them (see `isWriteTool` in the manual routes).
+  tags: ['plugins', 'skills', 'write'],
+});
+
+export const CREATE_PLUGIN: UtcpTool = toolDef({
+  name: 'create_plugin',
+  description:
+    "Create a shared plugin under the plugins root, exactly as the app's New plugin button does: the caller " +
+    'runs it (read, write and owner), and it is discoverable by everyone so people can ask to join. Pass ' +
+    '`parent` to make it inside an existing grouping folder under the plugins root (e.g. `Teams`); a plugin ' +
+    'cannot be made inside another plugin. Returns the folder and where its skills go. A refusal carries ' +
+    '`error` in words. 4xx means the input will not do: 409 when a plugin of that name (or its identifier) ' +
+    'exists, 422 for a name the knowledge base cannot carry or a parent that may not hold a plugin, 404 when ' +
+    'the parent folder is not there. 503 means the plugin list could not be read completely just now — ' +
+    'nothing is wrong with the input; try again shortly.',
+  path: '/api/plugins',
+  inputs: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', minLength: 1, description: 'The plugin name, e.g. `Design`. Becomes the folder name and the display name people see; its identifier is the kebab-case slug.' },
+      parent: {
+        type: 'string',
+        description: 'Optional grouping folder below the plugins root to create it in, e.g. `Teams` or `Teams/EU`. Omit for the root.',
+      },
+    },
+    required: ['name'],
+    additionalProperties: false,
+  },
+  outputs: PROVISIONED_OUTPUT,
+  // `write`: both make folders and commit — a read-scoped caller's manual
+  // must not advertise them (see `isWriteTool` in the manual routes).
+  tags: ['plugins', 'skills', 'write'],
+});

package/src/modules/plugins/teams.routes.ts

@@ -0,0 +1,129 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('teams');
+import { isPersonalPluginDir, isPersonalPluginFolder, pluginOfPath } from '@bevel-software/platform-shared';
+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 type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract.js';
+import { pluginsWorkspaceId } from './plugins.service.js';
+
+/**
+ * What one team can use, by id — the Library's "Your teams" lens.
+ *
+ * A team is a group from the active group source (`groups.yaml`, or the
+ * IdP-synced file), and what it can use is what being IN it lets a person
+ * read: the plugins whose rules admit the group, the skills those plugins
+ * link or hold, a shared skill whose own folder names the group, the tools
+ * declared in an admitted plugin. The verdict is the resolver's own
+ * (`canReadAsGroupBatch`), so a grant reached through a role that lists the
+ * group, or through `plugin/<name>/read` on a skill the group's plugin links,
+ * counts exactly as it does for a member.
+ *
+ * Every id is ALSO gated on the caller: a skill or tool the caller cannot
+ * read is not named here, however the team stands, and a plugin appears only
+ * when the caller could see it on the index (a member, or able to discover
+ * it). The lens never widens what the catalog already shows the caller — it
+ * slices it.
+ *
+ * The list opens with `Everyone`: not a group, the built-in org-wide
+ * principal — what a signed-in person in no group at all can use, which is
+ * what `read: everyone` (or a public plugin) reaches. Same slice, same
+ * caller gate, asked of the resolver as `canReadAsEveryoneBatch`. The name
+ * cannot collide with a group's: `everyone` is reserved by the grammar.
+ */
+export interface TeamAccess {
+  name: string;
+  /** Plugin identities (manifest names) the team's members can read. */
+  plugins: string[];
+  /** Skill names. */
+  skills: string[];
+  /** Tool slugs. */
+  tools: string[];
+}
+
+/** The org-wide entry's name — the built-in `everyone` principal, as the sidebar spells it. */
+export const EVERYONE_TEAM = 'Everyone';
+
+export function createTeamsRoutes(
+  accessControl: IAccessControl,
+  pluginIndex: IPluginIndexService,
+  skillService: Pick<ISkillService, 'listSkills'>,
+  toolManuals: Pick<IToolManualService, 'listAllSummaries'>,
+): express.Router {
+  const router = express.Router();
+
+  router.get('/teams', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    try {
+      const wsId = pluginsWorkspaceId();
+      const [{ groups }, catalog, allSkills, allTools] = await Promise.all([
+        accessControl.kbPrincipals(wsId),
+        pluginIndex.catalog(),
+        skillService.listSkills(),
+        toolManuals.listAllSummaries(),
+      ]);
+      // A personal plugin is one person's space, not a team's: it has no
+      // roster and admits nobody, so neither it nor anything inside it can
+      // be a team's to read — whatever a hand-written grant in there says.
+      // One rule for the plugin and for its contents, so the two cannot
+      // disagree.
+      const plugins = catalog.filter((g) => !g.folders.every(isPersonalPluginDir));
+      const skills = allSkills.filter((s) => !inPersonalPlugin(s.path));
+      const tools = allTools.filter((t) => !inPersonalPlugin(t.path));
+      const folderProbes = plugins.flatMap((g) => g.folders);
+      const discoverProbes = folderProbes.map(accessMdOf);
+      const skillProbes = skills.map((s) => skillMdOf(s.path));
+      const toolProbes = tools.map((t) => t.path);
+      const probes = [...new Set([...folderProbes, ...discoverProbes, ...skillProbes, ...toolProbes])];
+
+      const caller = await accessControl.canReadBatch(wsId, email, probes);
+      const callerReads = (p: string) => caller.get(p) === true;
+      const callerSeesPlugin = (g: PluginCatalogEntry) =>
+        g.folders.some((f) => callerReads(f) || callerReads(accessMdOf(f)));
+
+      /** One entry: what `verdicts` reads, cut to what the caller sees. */
+      const slice = (name: string, verdicts: Map<string, boolean>): TeamAccess => {
+        const reads = (p: string) => verdicts.get(p) === true;
+        return {
+          name,
+          plugins: plugins
+            .filter((g) => g.folders.some(reads) && callerSeesPlugin(g))
+            .map((g) => g.name),
+          skills: skills
+            .filter((s) => reads(skillMdOf(s.path)) && callerReads(skillMdOf(s.path)))
+            .map((s) => s.name),
+          tools: tools.filter((t) => reads(t.path) && callerReads(t.path)).map((t) => t.slug),
+        };
+      };
+
+      const teams: TeamAccess[] = [
+        slice(EVERYONE_TEAM, await accessControl.canReadAsEveryoneBatch(wsId, probes)),
+      ];
+      for (const name of groups) {
+        const team = await accessControl.canReadAsGroupBatch(wsId, name, probes);
+        if (team === null) continue; // gone between the two reads — nothing to say
+        teams.push(slice(name, team));
+      }
+      res.json({ teams });
+    } catch (err) {
+      log.error('failed to list teams:', { err });
+      res.status(500).json({ error: 'Failed to list teams' });
+    }
+  });
+
+  return router;
+}
+
+const accessMdOf = (folder: string) => `${folder}/access.md`;
+const skillMdOf = (skillPath: string) => `${skillPath}/SKILL.md`;
+/** Under `Plugins/personal-<id>/…` — one person's space, whatever it grants. */
+const inPersonalPlugin = (repoPath: string) => {
+  const folder = pluginOfPath(repoPath);
+  return folder !== null && isPersonalPluginFolder(folder);
+};