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

package/src/modules/plugins/plugin-links.service.ts

@@ -0,0 +1,363 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  DEFAULT_BRANCH,
+  PLUGIN_MANIFEST_FILE,
+  linkedSkillRoots,
+  normalizeSkillRoot,
+  pluginManifestName,
+  renderPluginManifest,
+  skillUnderRoot,
+  withLinkedSkillRoots,
+  type AuthUser,
+} from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { AccessMutationService, accessMdPathForFolder } from '../access/access-mutation.service.js';
+import { pluginPrincipalKey } from '../access-model/access-grammar.js';
+import type { Principal } from '../access-model/access-splice.js';
+import { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { ISkillService } from '../skills/skills.contract.js';
+import type { ProvisionCommitDriver } from './plugin-provision.service.js';
+import { linksWorkspaceId, type PluginLinkIndex } from './plugin-links.js';
+
+/** A refusal the route passes through: message + HTTP status + a machine-readable kind. */
+export class PluginLinkError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly payload: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = 'PluginLinkError';
+  }
+}
+
+/**
+ * Linking shared skills into plugins — the writer behind "add an existing
+ * skill to this plugin".
+ *
+ * A link is TWO edits that only make sense together:
+ *
+ *   1. the skill's root goes into the plugin manifest's
+ *      `extensions["software.bevel.hexis"].skills` list (see
+ *      `HEXIS_LINKED_SKILLS_KEY`), which is what the catalog, the plugin page
+ *      and the compiled distribution read;
+ *   2. the skill folder's own `access.md` grants `read` to
+ *      `plugin/<Name>/read` and `write` to `plugin/<Name>/write`, which is
+ *      what lets the plugin's members actually read it — ownership decides,
+ *      the plugin is a view (see `plugin-principals.ts`).
+ *
+ * Which is why linking needs write on BOTH sides: on the plugin folder (to
+ * edit its manifest) and on the skill's root (to edit its access rules). A
+ * manager who lacks the second gets a 409 the UI turns into "request write
+ * access", not a link that silently shares nothing.
+ *
+ * Unlinking removes the manifest entry, and revokes the two tokens only when
+ * the actor may edit the skill's rules — otherwise the grant stays, and the
+ * skill page says so, for a skill editor to remove.
+ *
+ * Repair re-grants the tokens for a link that exists but whose grant was
+ * hand-removed: the amber dot's one action.
+ *
+ * Every operation is serialised on BOTH sides it writes — the plugin's
+ * manifest slug (the same key provisioning locks on) and the skill root whose
+ * access.md carries the grant — and lands as ordinary default-branch commits
+ * through the pending-commit driver, so the write gate and the per-user push
+ * gate apply exactly as they do to any edit.
+ */
+export class PluginLinksService {
+  private readonly locks = new WorkspaceMutex();
+  private readonly mutation: AccessMutationService;
+
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly commits: ProvisionCommitDriver,
+    private readonly accessControl: IAccessControl,
+    private readonly skillService: ISkillService,
+    private readonly links: PluginLinkIndex,
+    private readonly kbDirName: string,
+    private readonly events?: {
+      emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void;
+    },
+    private readonly onChanged?: () => void,
+  ) {
+    this.mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
+  }
+
+  async link(user: AuthUser, plugin: string, rawRoot: string): Promise<{ root: string; skills: string[] }> {
+    const folder = await this.pluginFolder(plugin);
+    const root = this.rootOrThrow(rawRoot);
+    const wsId = linksWorkspaceId();
+    await this.requirePluginWrite(wsId, user, folder);
+    const skills = await this.resolvedSkills(root);
+    if (skills.length === 0) {
+      throw new PluginLinkError(
+        `"${root}" holds no released skill. Link a skill folder, or a folder that contains skills.`,
+        422,
+        { kind: 'no-skills', root },
+      );
+    }
+    if (!(await this.accessControl.canWrite(wsId, user.email, accessMdPathForFolder(root)))) {
+      // The manager may edit the plugin but not the skill's rules — the link
+      // would share nothing. The UI offers the request path on this shape.
+      throw new PluginLinkError(
+        `You can't change who may read "${root}". Ask its editors for write access first.`,
+        409,
+        { kind: 'needs-skill-write', root },
+      );
+    }
+    return this.locks.runAll(this.lockKeys(folder, root), async () => {
+      const { manifest, manifestRel } = await this.readManifest(wsId, folder);
+      const roots = linkedSkillRoots(manifest);
+      // Manifest FIRST, grant second — two commits, deliberately in this
+      // order. The two files live in different folders and the commit
+      // pipeline is path-scoped, so there is no single commit to be had; what
+      // can be chosen is which half-state a failure leaves. Listed-but-not-
+      // shared is the visible one: the link index reports the missing grant,
+      // the card wears the amber dot, and Repair finishes the job. The other
+      // order would leave shared-but-not-listed — an over-share nothing
+      // surfaces.
+      if (!roots.includes(root)) {
+        await this.workspaceService.writeFile(
+          wsId,
+          manifestRel,
+          `${JSON.stringify(withLinkedSkillRoots(manifest, [...roots, root]), null, 2)}\n`,
+        );
+        await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, manifestRel, user);
+      }
+      await this.grantTokens(wsId, user, folder, root);
+      this.changed(wsId);
+      return { root, skills };
+    });
+  }
+
+  async unlink(user: AuthUser, plugin: string, rawRoot: string): Promise<{ root: string; revoked: boolean }> {
+    const folder = await this.pluginFolder(plugin);
+    const root = this.rootOrThrow(rawRoot);
+    const wsId = linksWorkspaceId();
+    await this.requirePluginWrite(wsId, user, folder);
+    return this.locks.runAll(this.lockKeys(folder, root), async () => {
+      const { manifest, manifestRel } = await this.readManifest(wsId, folder);
+      const roots = linkedSkillRoots(manifest);
+      if (!roots.includes(root)) {
+        throw new PluginLinkError(`"${root}" is not linked into ${folder}.`, 404, { kind: 'not-linked', root });
+      }
+
+      // Revoke FIRST, manifest second — the mirror of `link`'s ordering and
+      // for the same reason: a failure between the two must leave the
+      // visible half-state (listed, no grant → amber dot, Repair), never the
+      // silent one (unlisted, still shared). Revoke only where the actor may
+      // edit the skill's rules; otherwise the grant stays for a skill editor
+      // to remove — never a silent no-op that pretends it happened.
+      let revoked = false;
+      if (await this.accessControl.canWrite(wsId, user.email, accessMdPathForFolder(root))) {
+        let changed = false;
+        for (const principal of this.tokens(folder)) {
+          const r = await this.mutation.revoke(wsId, 'folder', root, principal, user.email, undefined, {
+            tokenMatch: 'exact',
+          });
+          changed ||= r.changed;
+        }
+        if (changed) {
+          await this.commits.runPendingCommit(
+            wsId,
+            DEFAULT_BRANCH,
+            `${this.kbDirName}/${accessMdPathForFolder(root)}`,
+            user,
+          );
+        }
+        revoked = true;
+      }
+      await this.workspaceService.writeFile(
+        wsId,
+        manifestRel,
+        `${JSON.stringify(withLinkedSkillRoots(manifest, roots.filter((r) => r !== root)), null, 2)}\n`,
+      );
+      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, manifestRel, user);
+      this.changed(wsId);
+      return { root, revoked };
+    });
+  }
+
+  async repair(user: AuthUser, plugin: string, rawRoot: string): Promise<{ root: string }> {
+    const folder = await this.pluginFolder(plugin);
+    const root = this.rootOrThrow(rawRoot);
+    const wsId = linksWorkspaceId();
+    // Everything under the lock, the manifest read included: a repair that
+    // checked the link and then waited on an unlink would re-grant a root the
+    // manifest no longer names.
+    return this.locks.runAll(this.lockKeys(folder, root), async () => {
+      const { manifest } = await this.readManifest(wsId, folder);
+      if (!linkedSkillRoots(manifest).includes(root)) {
+        throw new PluginLinkError(`"${root}" is not linked into ${folder}.`, 404, { kind: 'not-linked', root });
+      }
+      if (!(await this.accessControl.canWrite(wsId, user.email, accessMdPathForFolder(root)))) {
+        throw new PluginLinkError(`You can't change who may read "${root}".`, 403, {
+          kind: 'needs-skill-write',
+          root,
+        });
+      }
+      // The same retired-skill rule as `link`: a repair re-grants on the root.
+      await this.resolvedSkills(root);
+      await this.grantTokens(wsId, user, folder, root);
+      this.changed(wsId);
+      return { root };
+    });
+  }
+
+  // --- internal --------------------------------------------------------------
+
+  /**
+   * ONE reservation for both sides of a link: the plugin's manifest AND the
+   * skill root's access.md. Two plugins linking the same root write the same
+   * file, and serialising on the plugin alone let them interleave, one splice
+   * overwriting the other's grant. `runAll` takes both keys atomically, so
+   * nothing nests and no ordering discipline is needed.
+   */
+  private lockKeys(folder: string, root: string): string[] {
+    return [`plugin:${pluginManifestName(folder)}`, `root:${root}`];
+  }
+
+  /**
+   * The two grants a link carries: members read, managers write — written as
+   * the CANONICAL keys (slugged name), the spelling every comparison uses, so
+   * a repeated link finds its grant and an unlink finds what to revoke
+   * whatever the folder is called.
+   */
+  private tokens(folder: string): Principal[] {
+    const slug = pluginManifestName(folder);
+    return [
+      { kind: 'role', role: pluginPrincipalKey(slug, 'read') },
+      { kind: 'role', role: pluginPrincipalKey(slug, 'write') },
+    ];
+  }
+
+  private async grantTokens(wsId: string, user: AuthUser, folder: string, root: string): Promise<void> {
+    const [read, write] = this.tokens(folder);
+    const a = await this.mutation.grant(wsId, 'folder', root, 'read', read);
+    const b = await this.mutation.grant(wsId, 'folder', root, 'write', write);
+    if (a.changed || b.changed) {
+      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${a.editPath}`, user);
+    }
+  }
+
+  private rootOrThrow(raw: string): string {
+    const root = normalizeSkillRoot(raw);
+    if (root === null) {
+      throw new PluginLinkError('A skill path must be a repo-relative folder path.', 422, { kind: 'bad-root' });
+    }
+    return root;
+  }
+
+  /**
+   * Released skills under the root — the catalog's answer, not the file
+   * system's. A RETIRED skill is kept for its owners and never shared onward:
+   * the grant lands on the ROOT folder, so a root that holds a retired skill
+   * anywhere beneath it cannot be linked at all — the grant would reach the
+   * retired one too. The refusal names them so the manager can link the
+   * active skills individually instead.
+   */
+  private async resolvedSkills(root: string): Promise<string[]> {
+    const under = (await this.skillService.listSkills(undefined)).filter((s) => skillUnderRoot(s.path, root));
+    const retired = under.filter((s) => s.lifecycle === 'retired').map((s) => s.path);
+    if (retired.length > 0) {
+      throw new PluginLinkError(
+        `"${root}" holds retired skills (${retired.join(', ')}); a retired skill is never shared onward. Link the active skills one by one.`,
+        422,
+        { kind: 'retired-skills', root, retired },
+      );
+    }
+    return under.map((s) => s.path);
+  }
+
+  /**
+   * The exact on-disk plugin folder for `name`, or 404. Personal folders are
+   * not plugins, but that is the MEMBERSHIP's verdict (discovery marks the
+   * `personal-*` prefix personal only directly under the root), not a rule
+   * on the name — a nested plugin may be called anything.
+   */
+  private async pluginFolder(name: string): Promise<string> {
+    const trimmed = name.trim();
+    if (!trimmed || trimmed.includes('/') || trimmed.includes('\\')) {
+      throw new PluginLinkError('Unknown plugin', 404, { kind: 'unknown-plugin' });
+    }
+    const membership = await this.links.membership();
+    const links = membership.byPlugin.get(trimmed);
+    if (!links) {
+      throw new PluginLinkError('Unknown plugin', 404, { kind: 'unknown-plugin' });
+    }
+    if (!links.linksAreManaged) {
+      // A dialect plugin's links live in a file this platform does not write.
+      throw new PluginLinkError(
+        `${trimmed} is read from an external plugin format; edit its links in that repository.`,
+        409,
+        { kind: 'read-only-links' },
+      );
+    }
+    return trimmed;
+  }
+
+  /** The repo-relative folder of a known plugin (any depth). */
+  private async folderOf(plugin: string): Promise<string> {
+    const links = (await this.links.membership()).byPlugin.get(plugin);
+    if (!links) throw new PluginLinkError('Unknown plugin', 404, { kind: 'unknown-plugin' });
+    return links.folder;
+  }
+
+  private async requirePluginWrite(wsId: string, user: AuthUser, plugin: string): Promise<void> {
+    if (!(await this.accessControl.canWrite(wsId, user.email, await this.folderOf(plugin)))) {
+      // Same answer as an unknown plugin, so probing confirms nothing.
+      throw new PluginLinkError('Unknown plugin', 404, { kind: 'unknown-plugin' });
+    }
+  }
+
+  private async readManifest(
+    wsId: string,
+    plugin: string,
+  ): Promise<{ manifest: Record<string, unknown>; manifestRel: string }> {
+    const folder = await this.folderOf(plugin);
+    const manifestRel = `${this.kbDirName}/${folder}/${PLUGIN_MANIFEST_FILE}`;
+    const abs = path.join(await this.workspaceService.getWorkspacePath(wsId), manifestRel);
+    let manifest: Record<string, unknown> | null = null;
+    let text: string | null = null;
+    try {
+      text = await fs.readFile(abs, 'utf-8');
+    } catch (err) {
+      // Only a PROVEN absence gets the fresh minimal manifest a pre-manifest
+      // folder deserves. Any other failure must surface: the caller writes the
+      // manifest back, and a skeleton over a real one would erase its
+      // version, description and MCP extension block.
+      const code = (err as { code?: unknown } | null)?.code;
+      if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+    }
+    if (text !== null) {
+      try {
+        const parsed: unknown = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+          manifest = parsed as Record<string, unknown>;
+        }
+      } catch {
+        /* unparsable */
+      }
+      if (manifest === null) {
+        throw new PluginLinkError(
+          `${manifestRel} is not a JSON object; fix the manifest before changing its links.`,
+          422,
+          { kind: 'bad-manifest' },
+        );
+      }
+    }
+    return {
+      manifest: manifest ?? (JSON.parse(renderPluginManifest(path.posix.basename(folder))) as Record<string, unknown>),
+      manifestRel,
+    };
+  }
+
+  private changed(wsId: string): void {
+    this.links.invalidate();
+    this.accessControl.invalidate(wsId);
+    this.onChanged?.();
+    this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
+  }
+}

package/src/modules/plugins/plugin-links.ts

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import { DEFAULT_BRANCH, pluginManifestName, skillUnderRoot } 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 type { ISkillService } from '../skills/skills.contract.js';
+import { TtlCache } from '../../shared/ttl-cache.js';
+import { canonicalRoleName, pluginPrincipalKey } from '../access-model/access-grammar.js';
+import type { PluginMembership } from './plugins.contract.js';
+import type { PluginSource } from './discovery/plugin-source.js';
+import { KbPluginSource } from './discovery/kb-plugin-source.js';
+
+const CACHE_TTL_MS = 60_000;
+
+/** One plugin's links, resolved against the released catalog. */
+export interface PluginLinks {
+  /** The plugin's name — its identity to people and URLs. */
+  name: string;
+  /** Repo-relative plugin folder. */
+  folder: string;
+  /** The roots the manifest declares, normalised. */
+  roots: string[];
+  /** Skill folders the roots resolve to (released catalog only). */
+  linkedSkills: string[];
+  /** Roots that resolve to no released skill — a typo, or a skill not yet merged. */
+  unresolvedRoots: string[];
+  /** Whether hexis writes these links and checks their grants — see `DiscoveredPlugin`. */
+  linksAreManaged: boolean;
+}
+
+export interface LinkMembership {
+  /** skill path → every plugin that holds it, inline or by link. */
+  bySkill: Map<string, PluginMembership[]>;
+  /** plugin folder → its links. Every plugin folder appears, linked or not. */
+  byPlugin: Map<string, PluginLinks>;
+}
+
+/**
+ * The link index: which shared skills each plugin links, and — the other way
+ * round — which plugins each skill belongs to, whether by sitting inside the
+ * plugin folder or by being linked from its manifest.
+ *
+ * Plugins come from the configured {@link PluginSource} (native manifests, or
+ * a customer dialect); resolution runs against the RELEASED catalog
+ * (`skillService.listSkills()`, unfiltered), never the file system: the
+ * catalog already applies the leaf-folder rule, the `.bevelignore` layers
+ * and the global-name dedup, and a second walk here would be a second
+ * opinion about what a skill is.
+ *
+ * `granted` is the consistency check the amber dot renders: a linked skill
+ * whose own access rules DO grant the plugin's `plugin/<Name>/read`
+ * principal (directly or from a scope above it). The link service writes
+ * that grant with the link; only a hand edit takes it away.
+ *
+ * Cached briefly, dropped by `invalidate()` from the same file-change
+ * subscriber that drops the plugin index, so a link committed on the default
+ * branch shows within one round-trip.
+ */
+export class PluginLinkIndex {
+  private readonly cache: TtlCache<LinkMembership>;
+
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly skillService: ISkillService,
+    private readonly accessControl: IAccessControl,
+    private readonly kbDirName: string,
+    now: () => number = Date.now,
+    private readonly source: PluginSource = new KbPluginSource(),
+  ) {
+    this.cache = new TtlCache(CACHE_TTL_MS, now);
+  }
+
+  invalidate(): void {
+    this.cache.invalidate();
+  }
+
+  async membership(): Promise<LinkMembership> {
+    const cached = this.cache.get();
+    if (cached) return cached;
+    // Token first, like the other catalogs: an `invalidate()` landing while
+    // the build reads the pre-change tree must not be undone by storing that
+    // read afterwards.
+    const token = this.cache.begin();
+    const built = await this.build();
+    // A degraded read (no workspace yet) is served but not stored — the same
+    // reasoning as the plugin index: caching a failure hides every link for
+    // a full TTL after its cause is gone.
+    if (built === null) return { bySkill: new Map(), byPlugin: new Map() };
+    this.cache.set(built, token);
+    return built;
+  }
+
+  /** Convenience: the memberships of one skill (empty when it is in no plugin). */
+  async pluginsOf(skillPath: string): Promise<PluginMembership[]> {
+    return (await this.membership()).bySkill.get(skillPath) ?? [];
+  }
+
+  // --- internal --------------------------------------------------------------
+
+  private async build(): Promise<LinkMembership | null> {
+    let wsId: string;
+    let kbRoot: string;
+    try {
+      wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+      kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+    } catch {
+      return null;
+    }
+    const skills = await this.skillService.listSkills(undefined);
+    const bySkill = new Map<string, PluginMembership[]>();
+    const byPlugin = new Map<string, PluginLinks>();
+    const add = (skillPath: string, m: PluginMembership) => {
+      const list = bySkill.get(skillPath) ?? [];
+      if (!list.some((x) => x.name === m.name)) list.push(m);
+      bySkill.set(skillPath, list);
+    };
+
+    const discovered = await this.source.discover(kbRoot);
+    for (const w of discovered.warnings) console.warn(`[plugins] ${w}`);
+
+    // Inline skills: the ones sitting INSIDE a plugin's folder, matched by
+    // folder prefix (a plugin may sit at any depth, so the second path
+    // segment says nothing). Personal folders are places, not plugins —
+    // their skills belong to nobody's plugin.
+    const ownerOf = (skillPath: string) =>
+      discovered.plugins.find((p) => !p.personal && p.exists && skillPath.startsWith(`${p.folder}/`));
+    for (const s of skills) {
+      const owner = ownerOf(s.path);
+      if (owner) add(s.path, { name: owner.name, linked: false, granted: true });
+    }
+
+    for (const plugin of discovered.plugins) {
+      // Personal folders are places, not plugins; a manifest without the
+      // access.md that makes a plugin EXIST is a ghost the index and the
+      // compiler omit, so it must not be linkable or hold grants either.
+      if (plugin.personal || !plugin.exists) continue;
+      const roots = plugin.linkedRoots;
+      const linkedSkills: string[] = [];
+      const unresolvedRoots: string[] = [];
+      for (const root of roots) {
+        const hits = skills.filter((s) => skillUnderRoot(s.path, root)).map((s) => s.path);
+        if (hits.length === 0) unresolvedRoots.push(root);
+        for (const hit of hits) if (!linkedSkills.includes(hit)) linkedSkills.push(hit);
+      }
+      byPlugin.set(plugin.name, {
+        name: plugin.name,
+        folder: plugin.folder,
+        roots,
+        linkedSkills,
+        unresolvedRoots,
+        linksAreManaged: plugin.linksAreManaged,
+      });
+      if (linkedSkills.length === 0) continue;
+      const token = pluginPrincipalKey(pluginManifestName(plugin.name), 'read');
+      for (const skillPath of linkedSkills) {
+        // A skill that also sits INSIDE this plugin folder is inline, and its
+        // inline membership already stands.
+        if (skillPath.startsWith(`${plugin.folder}/`)) continue;
+        // An unmanaged (dialect) link is a plain reference: nothing to grant,
+        // nothing to repair — the skill's own scope decides who reads it.
+        const granted = plugin.linksAreManaged ? await this.isGranted(wsId, skillPath, token) : true;
+        add(skillPath, { name: plugin.name, linked: true, granted });
+      }
+    }
+    return { bySkill, byPlugin };
+  }
+
+  /** Whether the skill folder's effective readers include the plugin's read principal. */
+  private async isGranted(wsId: string, skillPath: string, token: string): Promise<boolean> {
+    try {
+      const readers = await this.accessControl.eligibleReaders(wsId, skillPath);
+      if (!readers.restricted) return true; // readable by everyone — the plugin's members included
+      // The resolver reports display names; compare through the one canonicaliser.
+      return (readers.principals ?? []).some((p) => p.kind === 'plugin' && canonicalRoleName(p.name) === token);
+    } catch {
+      return false; // fail closed: an unreadable tree reports the link as needing repair
+    }
+  }
+}
+
+/** The default-branch workspace id every link resolution runs against. */
+export function linksWorkspaceId(): string {
+  return workspaceIdForBranch(DEFAULT_BRANCH);
+}