@bevel-software/platform-shared 0.7.5 → 0.8.0

package/src/workspace/join-request.ts

@@ -1,15 +1,15 @@
 /**
- * The join-request naming convention — how "asking to join a group" rides on
+ * The join-request naming convention — how "asking to join a plugin" rides on
  * plain change requests with zero new backend state.
  *
  * A join request IS a change request: a draft branch carrying one commit that
- * adds the requester to the group's `access.md` body `read:` list, opened
+ * adds the requester to the plugin's `access.md` body `read:` list, opened
  * against the default branch. What makes it recognisable — to the `Requested`
  * chip, to the manager-side proposals surface, to idempotency — is only this
  * branch-name convention. Both sides (backend, frontend) read it from here so
  * they can never drift.
  *
- *   <email-localpart>/join-<group-kebab>-<groupTag>-<requesterTag>
+ *   <email-localpart>/join-<plugin-kebab>-<pluginTag>-<requesterTag>
  *
  * follows the workspace's existing `<email-localpart>/<kebab-slug>` draft
  * convention, so join branches sort with the requester's other drafts and
@@ -18,15 +18,15 @@
  * WHY TWO TAGS: the localpart and the kebab slug are both LOSSY, and each
  * loss has its own failure:
  *
- *  - `groupTag` — over the EXACT group name, recomputable by anyone who
- *    knows the group. `Finance!` and `finance` share the slug `finance`;
- *    without this tag, listing one group's requests would match the other's
+ *  - `pluginTag` — over the EXACT plugin name, recomputable by anyone who
+ *    knows the plugin. `Finance!` and `finance` share the slug `finance`;
+ *    without this tag, listing one plugin's requests would match the other's
  *    branches, read the wrong `access.md` (unchanged on that branch), see an
  *    empty diff and SETTLE the request — closing a change request and
- *    deleting a branch that belong to a different group. The settle decision
- *    is "the diff is empty", so group identity must be exact BEFORE the diff
+ *    deleting a branch that belong to a different plugin. The settle decision
+ *    is "the diff is empty", so plugin identity must be exact BEFORE the diff
  *    is consulted, and `isJoinBranchFor` recomputes this tag to make it so.
- *  - `requesterTag` — over the full email (+ group), NOT recomputable by a
+ *  - `requesterTag` — over the full email (+ plugin), NOT recomputable by a
  *    reader (a manager listing requests does not know each requester's
  *    email; `isJoinBranchFor` matches its shape only). It exists so
  *    `ali@bevel.software` and `ali@other.com` never share a branch — else
@@ -38,9 +38,9 @@
  * whose file adds nothing over the default branch.
  */
 
-/** Group name → the kebab slug used in the join branch (lossy by design). */
-export function kebabGroupName(group: string): string {
-  return group
+/** Plugin name → the kebab slug used in the join branch (lossy by design). */
+export function kebabPluginName(plugin: string): string {
+  return plugin
     .trim()
     .toLowerCase()
     .replace(/\s+/g, '-')
@@ -70,37 +70,43 @@ function shortTag(input: string): string {
   return hash.toString(36).padStart(TAG_LENGTH, '0').slice(-TAG_LENGTH);
 }
 
-/** The exact-group tag — recomputable from the group name alone. */
-function groupTag(group: string): string {
-  return shortTag(`g:${group}`);
+/** The exact-plugin tag — recomputable from the plugin name alone. */
+function pluginTag(plugin: string): string {
+  // `g:` predates the group→plugin rename, and it STAYS: the prefix is baked
+  // into every join branch already on a remote, and `isJoinBranchFor`
+  // recomputes this tag to recognise them. Changing it to `p:` would change
+  // every recomputed tag and orphan every in-flight join request. The prefix
+  // only disambiguates this tag's input from `u:<email>` — any stable byte
+  // does that, so there is nothing to gain by renaming it.
+  return shortTag(`g:${plugin}`);
 }
 
-/** The deterministic join branch for (requester, group). */
-export function joinBranchFor(email: string, group: string): string {
+/** The deterministic join branch for (requester, plugin). */
+export function joinBranchFor(email: string, plugin: string): string {
   const normalizedEmail = email.trim().toLowerCase();
   const localpart = normalizedEmail.split('@')[0] || normalizedEmail;
-  const slug = kebabGroupName(group);
-  const requester = shortTag(`u:${normalizedEmail}\n${group}`);
-  // A group whose name has no alphanumerics at all (`!!!`) kebabs to '' — the
+  const slug = kebabPluginName(plugin);
+  const requester = shortTag(`u:${normalizedEmail}\n${plugin}`);
+  // A plugin whose name has no alphanumerics at all (`!!!`) kebabs to '' — the
   // tags alone still yield a valid, matchable branch.
   const middle = slug ? `${slug}-` : '';
-  return `${localpart}/join-${middle}${groupTag(group)}-${requester}`;
+  return `${localpart}/join-${middle}${pluginTag(plugin)}-${requester}`;
 }
 
 /**
- * Does `branch` look like SOMEBODY's join branch for EXACTLY `group`?
+ * Does `branch` look like SOMEBODY's join branch for EXACTLY `plugin`?
  *
- * The group half (slug + `groupTag`) is recomputed and must match — this is
- * what keeps slug-colliding groups (`Finance!` vs `finance`) from seeing,
+ * The plugin half (slug + `pluginTag`) is recomputed and must match — this is
+ * what keeps slug-colliding plugins (`Finance!` vs `finance`) from seeing,
  * and worse settling, each other's requests. The requester half cannot be
  * recomputed (the reader has no email) and matches by shape; the requester's
  * identity comes from the change request's own attribution.
  */
-export function isJoinBranchFor(branch: string, group: string): boolean {
-  const slug = kebabGroupName(group);
+export function isJoinBranchFor(branch: string, plugin: string): boolean {
+  const slug = kebabPluginName(plugin);
   const middle = slug ? `${escapeRegExp(slug)}-` : '';
   const requester = `[0-9a-z]{${TAG_LENGTH}}`;
-  return new RegExp(`^[^/]+/join-${middle}${groupTag(group)}-${requester}$`).test(branch);
+  return new RegExp(`^[^/]+/join-${middle}${pluginTag(plugin)}-${requester}$`).test(branch);
 }
 
 function escapeRegExp(s: string): string {

package/src/workspace/kb-layout.ts

@@ -8,7 +8,7 @@ import { branchSegment } from '../git/branchAuthor.js';
  *
  *   <kbDirName>/
  *   ├── KnowledgeBase/   ← all team ontologies live here (the knowledge graph)
- *   ├── Groups/          ← one folder per group; each holds BOTH skills and tools
+ *   ├── Plugins/         ← one folder per plugin; each holds BOTH skills and tools
  *   ├── Data/            ← agent-produced records; parsed like KnowledgeBase/
  *   ├── Agents/          ← .agent files — agent role configurations (not the graph)
  *   ├── Pipelines/       ← .pipeline files — execution-layer processes (not the graph)
@@ -24,7 +24,7 @@ import { branchSegment } from '../git/branchAuthor.js';
  *
  * These names are the single source of truth for both sides of the app:
  *  - Backend: the graph parser discovers ontologies under the
- *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Groups/`,
+ *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Plugins/`,
  *    `Agents/`, `Pipelines/` (and anything else at the root) are ignored by
  *    parsing, validation, and the diagram.
  *  - Frontend: the file tree renders these root folders as distinct
@@ -37,36 +37,135 @@ import { branchSegment } from '../git/branchAuthor.js';
 export const KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
 
 /**
- * Folder under the repo root that holds the groups.
+ * Folder under the repo root that holds the plugins.
  *
- *   Groups/<Group>/<skill>/SKILL.md   a skill
- *   Groups/<Group>/<name>.tool        a tool manual
- *   Groups/<Group>/access.md          who can read/write the whole group
+ *   Plugins/<Plugin>/plugin.json                  the Agent Plugins manifest
+ *   Plugins/<Plugin>/skills/<skill>/SKILL.md      a skill
+ *   Plugins/<Plugin>/mcp.json                     MCP servers
+ *   Plugins/<Plugin>/software.bevel.hexis/tools/  http + inline `.tool` manuals
+ *   Plugins/<Plugin>/access.md                    who can read/write the plugin
  *
- * One folder is one group. Skills and tools live TOGETHER inside it because
- * they share a single access boundary: a tool a group cannot read is a skill
- * that group cannot run, so splitting them across two roots meant maintaining
- * the same permission twice and letting them drift.
+ * Each folder is one plugin, laid out per the Agent Plugins specification
+ * (https://agent-plugins.org, v1.0.0) so another conformant client can load it:
+ * it finds the manifest, the skills and the MCP servers, and ignores everything
+ * under the reverse-DNS extension directory.
  *
- * A group is not a registry of unique names — it is a folder. The same
- * integration may exist in several groups as separate files (`Everyone/
- * notion.tool` and `Finance/notion.tool`), each with its own credentials and
+ * Two parts of a plugin are ours and deliberately outside the portable core:
+ *
+ *  - `access.md`, which must sit at the PLUGIN ROOT. Access resolution walks
+ *    repo root → file directory accumulating rules, so the same file one level
+ *    down would govern only that subtree — silently narrowing what it protects.
+ *  - `software.bevel.hexis/tools/*.tool`, the UTCP manuals whose `http` and
+ *    `inline` types the spec has no slot for. `mcp`-type manuals are emitted as
+ *    real `mcp.json` entries instead, so the portable half stays portable.
+ *
+ * Skills and tools live TOGETHER in one plugin because they share a single
+ * access boundary: a tool a plugin cannot read is a skill that plugin cannot
+ * run, so splitting them across two roots meant maintaining the same permission
+ * twice and letting them drift.
+ *
+ * A plugin is not a registry of unique names — it is a folder. The same
+ * integration may exist in several plugins as separate files (`Everyone/…/
+ * notion.tool` and `Finance/…/notion.tool`), each with its own credentials and
  * its own access rule. That duplication is the design, not an accident.
+ *
+ * The DIRECTORY name is unconstrained by the spec (§4.1 — a plugin is located
+ * by path, and the name carries no meaning to a client), so folders keep their
+ * display casing. The lowercase slug the spec does constrain lives in the
+ * manifest's `name` field.
+ */
+export const PLUGINS_DIR = 'Plugins';
+
+/**
+ * The pre-rename name of {@link PLUGINS_DIR}. Referenced ONLY by the migration
+ * that renames it — every other consumer should be reading the new name, and a
+ * second live spelling is exactly how two layouts start being supported by
+ * accident.
+ */
+export const LEGACY_GROUPS_DIR = 'Groups';
+
+/** The manifest that makes a directory a plugin (Agent Plugins §4.1). */
+export const PLUGIN_MANIFEST_FILE = 'plugin.json';
+
+/** The MCP server configuration a conformant client reads (Agent Plugins §8). */
+export const PLUGIN_MCP_FILE = 'mcp.json';
+
+/** Where a plugin's skills live, one folder each (Agent Plugins §7.1). */
+export const PLUGIN_SKILLS_DIR = 'skills';
+
+/**
+ * Our reverse-DNS extension namespace. The spec reserves these directories for
+ * exactly this — client-specific behaviour that a portable core should not
+ * carry — so anything a conformant third-party client has no way to interpret
+ * goes here rather than loose in the plugin root.
  */
-export const GROUPS_DIR = 'Groups';
+export const HEXIS_EXTENSION_NS = 'software.bevel.hexis';
+
+/** UTCP manuals whose `http`/`inline` types the spec cannot express. */
+export const HEXIS_TOOLS_DIR = `${HEXIS_EXTENSION_NS}/tools`;
+
+/**
+ * The manifest `name` for a plugin folder: lowercased, anything outside
+ * `[a-z0-9.-]` folded to `-`, runs collapsed, ends trimmed to alphanumerics.
+ *
+ * The schema's pattern is `^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$`
+ * — so a folder like `personal-<user-id>` whose sanitized id happens to contain
+ * a doubled separator would produce an INVALID manifest, which is fatal to a
+ * conformant client. Collapsing runs is what makes that unrepresentable rather
+ * than merely unlikely.
+ */
+export function pluginManifestName(folderName: string): string {
+  const slug = folderName
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/\.{2,}/g, '.')
+    .replace(/^[^a-z0-9]+/, '')
+    .replace(/[^a-z0-9]+$/, '')
+    .slice(0, 64)
+    .replace(/[^a-z0-9]+$/, '');
+  // Every character can be stripped (a folder named `---`), and `name` is
+  // required — fall back rather than emit a manifest that fails validation.
+  return slug || 'plugin';
+}
+
+/** The schema a v1.0.0 manifest declares, and the version both files must agree on. */
+export const AGENT_PLUGINS_SCHEMA_VERSION = '1.0.0';
+export const PLUGIN_MANIFEST_SCHEMA = `https://agent-plugins.org/schemas/${AGENT_PLUGINS_SCHEMA_VERSION}/plugin.schema.json`;
+export const PLUGIN_MCP_SCHEMA = `https://agent-plugins.org/schemas/${AGENT_PLUGINS_SCHEMA_VERSION}/mcp.schema.json`;
+
+/**
+ * A minimal, valid `plugin.json` for a plugin folder.
+ *
+ * Deliberately only the two required fields. `version`, `license` and the rest
+ * are optional metadata about a DISTRIBUTED package, and inventing values for a
+ * folder someone just made in the app would be asserting things nobody said —
+ * a plugin here is a place a team keeps skills, not something published.
+ *
+ * The display name is the folder, which is why nothing here carries one: the
+ * manifest's `name` is constrained to a lowercase slug, and the field set is
+ * closed, so there is no conformant home for "Sales" other than an extension.
+ */
+export function renderPluginManifest(folderName: string): string {
+  return `${JSON.stringify(
+    { $schema: PLUGIN_MANIFEST_SCHEMA, name: pluginManifestName(folderName) },
+    null,
+    2,
+  )}\n`;
+}
 
 /**
- * The reserved name prefix marking a personal folder under `Groups/` —
- * `Groups/personal-<user-id>/` is where a person's own skills live: created
+ * The reserved name prefix marking a personal folder under `Plugins/` —
+ * `Plugins/personal-<user-id>/` is where a person's own skills live: created
  * implicitly on their first personal skill, private by default (its seeded
  * `access.md` names only its owner), and never listed as a group.
  *
  * The marker is STRUCTURAL on purpose: every surface that enumerates groups
  * (catalog scan, sidebar, counts) filters on the name alone, with no access
- * lookup needed, and the group-creation endpoint refuses names carrying the
- * prefix — so a regular group can never squat on someone's personal folder.
+ * lookup needed, and the plugin-creation endpoint refuses names carrying the
+ * prefix — so a regular plugin can never squat on someone's personal folder.
  */
-export const PERSONAL_GROUP_PREFIX = 'personal-';
+export const PERSONAL_PLUGIN_PREFIX = 'personal-';
 
 /**
  * The one personal folder name for a user — keyed to the STABLE user id, not
@@ -76,34 +175,34 @@ export const PERSONAL_GROUP_PREFIX = 'personal-';
  * sanitizer — the id lands in the folder name exactly as it lands in the
  * user's suggestion-branch names, so the two spellings can never disagree.
  */
-export function personalGroupFolderName(userId: string): string {
-  return `${PERSONAL_GROUP_PREFIX}${branchSegment(userId)}`;
+export function personalPluginFolderName(userId: string): string {
+  return `${PERSONAL_PLUGIN_PREFIX}${branchSegment(userId)}`;
 }
 
-/** Whether a `Groups/` child is somebody's personal folder. */
-export function isPersonalGroupFolder(folderName: string): boolean {
-  return folderName.startsWith(PERSONAL_GROUP_PREFIX);
+/** Whether a `Plugins/` child is somebody's personal folder. */
+export function isPersonalPluginFolder(folderName: string): boolean {
+  return folderName.startsWith(PERSONAL_PLUGIN_PREFIX);
 }
 
 /**
- * The group a repo-root-relative path belongs to, or `null` for content that
- * sits outside any group.
+ * The plugin a repo-root-relative path belongs to, or `null` for content that
+ * sits outside any plugin.
  *
- *   Groups/GTM/heyreach-campaign/SKILL.md → 'GTM'
- *   Groups/GTM/heyreach.tool              → 'GTM'
- *   Groups/loose-skill/SKILL.md           → null    (no group folder)
- *   KnowledgeBase/Product/…               → null    (not a group root)
+ *   Plugins/GTM/skills/heyreach-campaign/SKILL.md → 'GTM'
+ *   Plugins/GTM/mcp.json                          → 'GTM'
+ *   Plugins/loose-skill/SKILL.md                  → 'loose-skill' (the folder IS the plugin)
+ *   KnowledgeBase/Product/…                       → null    (not a plugin root)
  *
- * Returns null rather than throwing because a group is a property SOME paths
- * have. Callers bucket by it; nothing requires it. An ungrouped skill is a
+ * Returns null rather than throwing because a plugin is a property SOME paths
+ * have. Callers bucket by it; nothing requires it. A plugin-less skill is a
  * real, supported state — the prototype calls those "yours alone".
  */
-export function groupOfPath(repoRelativePath: string): string | null {
+export function pluginOfPath(repoRelativePath: string): string | null {
   const segments = repoRelativePath.split('/').filter(Boolean);
-  if (segments[0] !== GROUPS_DIR) return null;
-  // Needs a segment for the group AND at least one below it, otherwise
-  // `Groups/GTM` (the folder itself) would report itself as being in a group,
-  // and a loose `Groups/slack.tool` would report a group named "slack.tool".
+  if (segments[0] !== PLUGINS_DIR) return null;
+  // Needs a segment for the plugin AND at least one below it, otherwise
+  // `Plugins/GTM` (the folder itself) would report itself as being in a plugin,
+  // and a loose `Plugins/slack.tool` would report a plugin named "slack.tool".
   return segments.length >= 3 ? (segments[1] ?? null) : null;
 }