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

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

@@ -0,0 +1,310 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  PERSONAL_PLUGIN_PREFIX,
+  PLUGIN_MANIFEST_FILE,
+  isPluginIdentifier,
+  pluginDisplayNameOf,
+  pluginManifestName,
+} from '@bevel-software/platform-shared';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
+import type { ITreeWalker, WalkListener } from '../../shared/fs.contract.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import {
+  PLUGIN_TOKEN_PREFIX,
+  canonicalPluginToken,
+  hasAccessFrontmatterExtension,
+  parsePluginPrincipalKey,
+} from '../access-model/access-grammar.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { PluginSource } from './discovery/plugin-source.js';
+import { linksWorkspaceId } from './plugin-links.js';
+
+export class PluginRenameError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly payload: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = 'PluginRenameError';
+  }
+}
+
+/** The one commit the rename lands as — a scoped batch, pushed. */
+export interface RenameCommitDriver {
+  commitChanges(workspaceId: string, user: AuthUser, summary: string, onlyPaths: string[]): Promise<unknown>;
+}
+
+export interface RenameResult {
+  name: string;
+  displayName: string;
+  /** Repo-relative files whose grants were rewritten, for the response and the log. */
+  rewritten: string[];
+}
+
+/**
+ * Renaming a plugin — its identifier, its display name, or both.
+ *
+ * The identifier (the manifest's `name`) IS the plugin: the marketplace
+ * publishes it, the URLs key on it, and every grant of `plugin/<name>/<verb>`
+ * spells it. Changing it is therefore a rename of a PRINCIPAL, and a
+ * principal that is renamed in one file and not another is two principals,
+ * one of which nobody is a member of. So the rename is one commit: the
+ * manifest, plus every access entry in the knowledge base that names the old
+ * identifier, rewritten to the new one. Membership does not change — the
+ * same people hold the same verbs through the new spelling — but the caller
+ * still needs write on each file the commit touches: the protected-branch
+ * gate checks every path, and a rename that lands in some files and is
+ * refused in others is the split it exists to prevent. The refusal names the
+ * files, so the manager can ask their editors or an admin.
+ *
+ * The display name is free text with no consequences: the manifest changes,
+ * nothing else does.
+ */
+export class PluginRenameService {
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly commits: RenameCommitDriver,
+    private readonly accessControl: IAccessControl,
+    private readonly source: PluginSource,
+    private readonly disk: ITreeWalker,
+    private readonly kbDirName: string,
+    private readonly events?: {
+      emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void;
+    },
+    private readonly onChanged?: () => void,
+  ) {}
+
+  private noteChanged(wsId: string): void {
+    noteChangedFor(this.accessControl, this.events, this.onChanged, wsId);
+  }
+
+  /** The READ phase must have seen everything it needed; a hole refuses the rename before any write. */
+  private assertComplete(unreadable: string[]): void {
+    if (unreadable.length === 0) return;
+    throw new PluginRenameError(
+      `Some of the knowledge base could not be read (${unreadable.join(', ')}), so the rename cannot be checked against every plugin and grant. Try again, or ask an admin.`,
+      503,
+      { kind: 'incomplete-discovery', unreadable },
+    );
+  }
+
+  async rename(
+    user: AuthUser,
+    current: string,
+    patch: { name?: unknown; displayName?: unknown },
+  ): Promise<RenameResult> {
+    const wsId = linksWorkspaceId();
+    const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+    // ONE walk of the checkout for everything the rename needs to know:
+    // the plugins (discovery's listener) and every file that can carry a
+    // grant (this one's), seeing one set of holes. Listing is all that
+    // happens here — no file is read, nothing is decided — so it can run
+    // before authorization without telling anyone anything.
+    const grantFiles: string[] = [];
+    const grantListener: WalkListener = {
+      onFile(dir, name) {
+        if (hasAccessFrontmatterExtension(name)) grantFiles.push(dir ? `${dir}/${name}` : name);
+      },
+    };
+    const { discovery, holes } = this.source.walkWith
+      ? await this.source.walkWith(kbRoot, [grantListener])
+      : { discovery: await this.source.discover(kbRoot), holes: (await this.disk.walkKb(kbRoot, [grantListener])).holes };
+    const { plugins } = discovery;
+    const unreadable = [...new Set([...discovery.unreadable, ...holes])];
+    // Three phases: READ everything, DECIDE, then WRITE. Nothing about the
+    // tree — not even that part of it could not be read — reaches a caller
+    // before they are known to manage the plugin they name.
+    const plugin = plugins.find((p) => p.name === current.trim() && !p.personal && p.exists);
+    // Fail closed, like every plugin surface: unknown and not-yours answer alike.
+    if (!plugin || !(await this.accessControl.canWrite(wsId, user.email, `${plugin.folder}/access.md`))) {
+      throw new PluginRenameError('Unknown plugin', 404, { kind: 'unknown-plugin' });
+    }
+    if (!plugin.linksAreManaged) {
+      throw new PluginRenameError(
+        `${plugin.name} is read from an external plugin format; rename it in that repository.`,
+        409,
+        { kind: 'read-only' },
+      );
+    }
+    const nextName = patch.name === undefined ? plugin.name : String(patch.name).trim();
+    // The rules govern a NEW identifier only. The current one is whatever the
+    // manifest says — a hand-written name that predates a rule (a reserved
+    // prefix, say) must not block a display-name change, and cannot be
+    // "fixed" by a rename that keeps it.
+    const identifierChanges = nextName !== plugin.name;
+    // A NEW identifier is claimed against EVERY plugin there is and rewritten
+    // into every grant there is. A listing with a hole in it — a folder or
+    // manifest that exists but could not be read — is neither set: the name
+    // could belong to what was not seen, the grant could live there. Fail
+    // closed; nothing is written. A display-name change claims nothing and
+    // touches one manifest, so it needs no more than its own plugin read.
+    if (identifierChanges) this.assertComplete(unreadable);
+    // An identifier must be its own slug: the marketplace and the collision
+    // checks key on `pluginManifestName(name)`, so a name that does not
+    // round-trip (longer than the slug's 64 characters, say) would be one
+    // thing here and another everywhere it is published.
+    if (identifierChanges && (!isPluginIdentifier(nextName) || pluginManifestName(nextName) !== nextName)) {
+      throw new PluginRenameError(
+        'A plugin identifier is lowercase kebab-case: letters, digits and single hyphens, like "sales-team".',
+        422,
+        { kind: 'bad-name' },
+      );
+    }
+    if (identifierChanges && nextName.startsWith(PERSONAL_PLUGIN_PREFIX)) {
+      throw new PluginRenameError(
+        `The "${PERSONAL_PLUGIN_PREFIX}" namespace is reserved for personal folders. Pick another identifier.`,
+        422,
+        { kind: 'bad-name' },
+      );
+    }
+    // Taken by SLUG, not by spelling: a bundle may declare a name that is not
+    // an identifier, and the marketplace folds every name to its slug — a
+    // collision there drops one of the two from the catalog.
+    if (identifierChanges && plugins.some((p) => p !== plugin && pluginManifestName(p.name) === nextName)) {
+      throw new PluginRenameError(`A plugin named "${nextName}" already exists.`, 409, { kind: 'name-taken' });
+    }
+    // What the MANIFEST says today, not what discovery resolved: a manifest
+    // carrying no `displayName` shows its identifier, and carrying THAT over
+    // an identifier change would persist the name the plugin just stopped
+    // being called. The stored field is the only thing an untouched display
+    // name can mean.
+    const storedDisplay =
+      typeof plugin.manifest?.displayName === 'string' ? plugin.manifest.displayName.trim() : '';
+    const nextDisplay =
+      patch.displayName === undefined ? storedDisplay : String(patch.displayName).trim();
+
+    // The manifest, with everything else in it kept. `displayName` is ALWAYS
+    // written — equal to the identifier, equal to the folder, whatever the
+    // person typed — because the manifest is the only source every reader
+    // has. The field is never deleted: an edit that blanks it falls back to
+    // the identifier, which is what the plugin is then called.
+    const manifest: Record<string, unknown> = { ...(plugin.manifest ?? {}), name: nextName };
+    manifest.displayName = nextDisplay || nextName;
+    const manifestRel = `${this.kbDirName}/${plugin.folder}/${PLUGIN_MANIFEST_FILE}`;
+    const writes: { rel: string; text: string; before: string | null }[] = [
+      { rel: manifestRel, text: `${JSON.stringify(manifest, null, 2)}\n`, before: plugin.manifestText },
+    ];
+
+    if (identifierChanges) {
+      // Every access entry in the knowledge base that names the old
+      // principal — in a folder's access.md or in the own frontmatter of any
+      // file kind the resolver reads grants from (`.md`, `.tool`, whatever
+      // an overlay registered). The files came from the walk above, whose
+      // holes have already refused: a folder that could not be listed would
+      // leave the old spelling live in it, and a principal renamed in some
+      // files and not others is two principals. A file the walk listed but
+      // that cannot be opened is the same hole: every such file is
+      // collected, then refused together.
+      const unopened: string[] = [];
+      for (const rel of grantFiles) {
+        const abs = path.join(kbRoot, rel);
+        let before: string;
+        try {
+          before = await fs.readFile(abs, 'utf-8');
+        } catch {
+          unopened.push(rel);
+          continue;
+        }
+        const after = renamePluginPrincipalInText(before, plugin.name, nextName);
+        if (after !== before) writes.push({ rel: `${this.kbDirName}/${rel}`, text: after, before });
+      }
+      this.assertComplete(unopened);
+      const denied: string[] = [];
+      for (const w of writes.slice(1)) {
+        const repoRel = w.rel.slice(this.kbDirName.length + 1);
+        if (!(await this.accessControl.canWrite(wsId, user.email, repoRel))) denied.push(repoRel);
+      }
+      if (denied.length > 0) {
+        throw new PluginRenameError(
+          `Renaming ${plugin.name} would rewrite grants in files you can't edit: ${denied.join(', ')}. Ask their editors, or an admin.`,
+          409,
+          { kind: 'needs-write', files: denied },
+        );
+      }
+    }
+
+    // Writes and commit share ONE failure envelope: whichever of them fails,
+    // the working tree goes back to what origin has — a half-written batch
+    // is as much a split principal as a refused commit.
+    try {
+      for (const w of writes) await this.workspaceService.writeFile(wsId, w.rel, w.text);
+      const summary = identifierChanges
+        ? `Rename plugin ${plugin.name} to ${nextName}`
+        : `Rename plugin ${plugin.name}: display name`;
+      await this.commits.commitChanges(
+        wsId,
+        user,
+        summary,
+        writes.map((w) => w.rel),
+      );
+    } catch (err) {
+      // One failure is NOT a failed commit: the commit landed locally and only
+      // the push did not (the typed hand-off the workflow throws). Restoring
+      // the old bytes then would stack an uncommitted inverse of a real
+      // commit; the recovery flow owns that state, so it is left alone — and
+      // since the tree DID change, every cache keyed on the old identity is
+      // dropped before the error goes up, exactly as on success.
+      if (err instanceof PushNeedsAgentResolutionError) {
+        this.noteChanged(wsId);
+      } else {
+        for (const w of writes) {
+          if (w.before !== null) await this.workspaceService.writeFile(wsId, w.rel, w.before).catch(() => undefined);
+        }
+      }
+      throw err;
+    }
+    this.noteChanged(wsId);
+    // Exactly what was persisted, read back through the shared rule — the
+    // response and the file can never say two different things.
+    return {
+      name: nextName,
+      displayName: pluginDisplayNameOf(manifest),
+      rewritten: writes.slice(1).map((w) => w.rel.slice(this.kbDirName.length + 1)),
+    };
+  }
+}
+
+/**
+ * The tree changed: drop the resolver's model and the plugin caches, and
+ * tell every session. The ONE place this happens, for the landed commit and
+ * for the committed-but-unpushed one alike.
+ */
+function noteChangedFor(
+  accessControl: IAccessControl,
+  events: PluginRenameService['events'],
+  onChanged: (() => void) | undefined,
+  wsId: string,
+): void {
+  accessControl.invalidate(wsId);
+  events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: linksWorkspaceIdBranch() });
+  onChanged?.();
+}
+
+/**
+ * Every access entry line naming `plugin/<old>/<verb>` — in ANY spelling the
+ * parser accepts — rewritten to `plugin/<next>/<verb>`, the rest of the
+ * line (indent, `- `, a `deny` prefix, the line ending) kept. Lines that are
+ * not such an entry are untouched, so the file's own formatting survives.
+ */
+export function renamePluginPrincipalInText(text: string, oldName: string, nextName: string): string {
+  const oldSlug = pluginManifestName(oldName);
+  return text
+    .split('\n')
+    .map((line) => {
+      const m = /^(\s*-\s+(?:deny\s+)?)(\S.*?)(\s*)$/i.exec(line);
+      if (!m) return line;
+      const key = canonicalPluginToken(m[2]!);
+      const parsed = key === null ? null : parsePluginPrincipalKey(key);
+      if (!parsed || parsed.slug !== oldSlug) return line;
+      return `${m[1]}${PLUGIN_TOKEN_PREFIX}${nextName}/${parsed.verb}${m[3]}`;
+    })
+    .join('\n');
+}
+
+function linksWorkspaceIdBranch(): string {
+  // The default branch's workspace id IS its encoded branch name.
+  return decodeURIComponent(linksWorkspaceId());
+}

package/src/modules/plugins/plugins.contract.ts

@@ -33,6 +33,8 @@
  * change requests; only the UI dresses them up.
  */
 
+export type { PluginMembership } from '../skills/skills.contract.js';
+
 /** Access-rule principals as the resolver hands them back. */
 export interface ResolvedPrincipals {
   roles: string[];
@@ -45,10 +47,26 @@ export interface ResolvedReaders extends ResolvedPrincipals {
 
 /** One plugin as `GET /api/plugins` reports it, resolved for ONE caller. */
 export interface PluginSummary {
-  /** Plugin folder name, e.g. `GTM`. */
+  /** The plugin's identity — its manifest name, e.g. `gtm`. */
   name: string;
+  /** What a person sees it called, e.g. `GTM`. */
+  displayName: string;
   /** Repo-relative constituent folders, e.g. `['Plugins/GTM']`. */
   folders: string[];
+  /**
+   * Repo-relative roots the plugin LINKS — its manifest's linked-skill roots
+   * (`extensions["software.bevel.hexis"].skills`), or a bundle's
+   * `sourceSkillRoots`.
+   *
+   * Served because a plugin's page has to say which of its cards live
+   * somewhere else. A SKILL carries its own membership record (linked or
+   * inline); a TOOL carries none — a `.tool` sitting beside the skills under
+   * a linked root reaches the plugin exactly the way those skills do, and
+   * these roots are the only thing that says so.
+   */
+  linkedRoots: string[];
+  /** Whether this platform writes the plugin's links — see `PluginCatalogEntry`. */
+  linksAreManaged: boolean;
   /**
    * Per-caller: the caller can read the FOLDER (membership). Every returned
    * plugin has at least one of `canRead` / `canWrite` / discoverability; a
@@ -71,17 +89,43 @@ export interface PluginSummary {
   /** Caller-INDEPENDENT total (the plugin's whole content, not the caller's slice). */
   skillCount: number;
   toolCount: number;
+  /**
+   * Caller-INDEPENDENT: how many of the plugin's LINKED skills its members
+   * cannot read — the link is in the manifest, but the skill folder no
+   * longer grants the plugin's readers. Counted here, from the unfiltered
+   * link index, because the people who most need the warning are the
+   * plugin's managers, and they are exactly the people a missing grant
+   * locks out: a count derived from what the caller can read would be zero
+   * for them. Zero for a plugin whose links are not managed here.
+   */
+  brokenLinks: number;
   /** For display: "Run by …" (fallback chain: owners → writers → 'the workspace admins'). */
   owners: ResolvedPrincipals;
   writers: ResolvedPrincipals;
   readers: ResolvedReaders;
+  /** The plugin's access.md says of itself that it is private — see `PluginCatalogEntry.isPrivate`. */
+  isPrivate: boolean;
+  /** What discovery left out of this plugin and why — see `PluginCatalogEntry.warnings`. */
+  warnings: string[];
   /**
-   * The caller has an OPEN join change request for this plugin (their
-   * deterministic join branch has an open CR). Always false for a member.
+   * The caller has asked to join this plugin and the ask still stands: a
+   * recorded request that is pending, one whose change request is still
+   * open, or an open join change request on their deterministic join branch.
+   * The RECORD is what makes this true the moment the subscribe call is
+   * answered — the change request may still be seconds away. False again
+   * once that change request is declined or settled: the ask is over, and
+   * the person may make it again. Always false for a member.
    */
   hasRequested: boolean;
-  /** The open join CR's number when `hasRequested` (deep-links the UI). */
+  /** The join CR's number once it exists (deep-links the UI); null before that. */
   requestNumber: number | null;
+  /**
+   * Why the last recorded request could not be sent, in the words the git
+   * work used — set only when `hasRequested` is false because the record
+   * failed, which is when the page owes the person the button back and a
+   * reason. Null in every other case, including on a server without records.
+   */
+  requestFailure?: string | null;
 }
 
 /**
@@ -90,13 +134,44 @@ export interface PluginSummary {
  * appears at all) are resolved per request in the route.
  */
 export interface PluginCatalogEntry {
+  /** The plugin's identity — its manifest name. */
   name: string;
+  /** What a person sees it called — the manifest's `displayName`, else its `name`. */
+  displayName: string;
   folders: string[];
+  /** The roots it links skills from — see `PluginSummary.linkedRoots`. */
+  linkedRoots: string[];
+  /**
+   * Whether this platform writes the plugin's links (a native `plugin.json`)
+   * — false for a plugin read from an external format, whose links are
+   * edited in that repository and which the link endpoints refuse.
+   */
+  linksAreManaged: boolean;
   skillCount: number;
   toolCount: number;
+  /** Linked skills the members cannot read — see `PluginSummary.brokenLinks`. */
+  brokenLinks: number;
   owners: ResolvedPrincipals;
   writers: ResolvedPrincipals;
   readers: ResolvedReaders;
+  /**
+   * The folder's access.md FRONTMATTER denies `everyone` read and names
+   * nobody but people (`isPrivateAccessMd`) — the shape a personal space is
+   * seeded with, and what a person writes to keep a plugin to a few named
+   * colleagues. The Library marks such a plugin "Private". A statement the
+   * file makes about itself, not a verdict: `readers` says who can use it.
+   */
+  isPrivate: boolean;
+  /**
+   * What discovery left out of THIS plugin and why, in plain words: an MCP
+   * server its profile selects that the registry could not keep, a skill
+   * root that is not a folder, a profile that does not exist. Attributed by
+   * folder from the discovery warnings, with the folder prefix removed, so
+   * the plugin's page can list them for the people who can fix the files —
+   * the server log is not where a plugin's owner looks. Empty when nothing
+   * was left out.
+   */
+  warnings: string[];
 }
 
 export interface IPluginIndexService {