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

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

@@ -31,8 +31,12 @@
  *     personal skill.
  */
 
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { isAbsence } from '../../shared/fs-errors.js';
+import type { Discovery, PluginSource } from './discovery/plugin-source.js';
+import { KbPluginSource } from './discovery/kb-plugin-source.js';
 
 import {
   DEFAULT_BRANCH,
@@ -41,8 +45,9 @@ import {
   pluginManifestName,
   renderPluginManifest,
   PERSONAL_PLUGIN_PREFIX,
-  isPersonalPluginFolder,
+  isPersonalPluginDir,
   personalPluginFolderName,
+  validateFilename,
   type AuthUser,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -62,9 +67,40 @@ export interface ProvisionCommitDriver {
   ): Promise<void>;
 }
 
+/**
+ * A directory's entries, or null when there is no such directory. ONLY
+ * absence reads as "nothing there": a listing that fails for any other
+ * reason (permissions, I/O) throws, because "the folder is not there" and
+ * "the folder could not be read" must never collapse into one answer — the
+ * first is a 404 to a caller, the second an outage an operator must see.
+ */
+async function listDirOrIncomplete(
+  dir: string,
+  repoRel: string,
+): Promise<Array<{ name: string; isDirectory(): boolean }> | null> {
+  try {
+    return await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isAbsence(err)) return null;
+    // The same refusal a hole in discovery gets: this listing is one more
+    // read the operation needed and could not have.
+    throw incompleteDiscovery([repoRel]);
+  }
+}
+
+/** The refusal for a discovery with a hole in it: a name cannot be checked, an identity cannot be known. */
+function incompleteDiscovery(unreadable: string[]): PluginProvisionError {
+  return new PluginProvisionError(
+    `Some of the knowledge base could not be read (${unreadable.join(', ')}), so the plugin cannot be checked against every other. Try again, or ask an admin.`,
+    503,
+  );
+}
+
 export interface ProvisionedPlugin {
   /** The folder name under `Plugins/` (not the full path). */
   folder: string;
+  /** The plugin's identity — the manifest name written for it. */
+  name: string;
   /** False when an ensure found the folder already there. */
   created: boolean;
 }
@@ -97,6 +133,8 @@ export class PluginProvisionService {
     private readonly accessControl: IAccessControl,
     private readonly kbDirName: string,
     private readonly events?: { emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void },
+    /** Which names are TAKEN is discovery's answer — the same one every catalog gets. */
+    private readonly source: PluginSource = new KbPluginSource(),
   ) {}
 
   /**
@@ -108,9 +146,9 @@ export class PluginProvisionService {
   async createPlugin(user: AuthUser, rawName: string): Promise<ProvisionedPlugin> {
     const name = rawName.trim();
     if (!name) throw new PluginProvisionError('A plugin needs a name.', 422);
-    // eslint-disable-next-line no-control-regex -- NUL and control chars are
-    // exactly what a filesystem path cannot carry; refusing them here keeps
-    // the refusal a 422 instead of the fs layer's 500.
+    // NUL and control chars are exactly what a filesystem path cannot carry;
+    // refusing them here keeps the refusal a 422 instead of the fs layer's 500.
+    // eslint-disable-next-line no-control-regex
     if (/[/\\\u0000-\u001f\u007f]/.test(name) || name === '.' || name === '..' || name.startsWith('.')) {
       throw new PluginProvisionError(
         'A plugin name can\'t contain / or \\ or control characters, or start with a dot.',
@@ -156,7 +194,7 @@ export class PluginProvisionService {
         );
       }
       await this.provision(user, name, pluginAccessMd(user));
-      return { folder: name, created: true };
+      return { folder: name, name: pluginManifestName(name), created: true };
     });
   }
 
@@ -168,7 +206,7 @@ export class PluginProvisionService {
     const folder = personalPluginFolderName(user.id);
     return this.creations.run(`plugin:${pluginManifestName(folder)}`, async () => {
       if ((await this.existingFolder(folder)) !== null) {
-        return { folder, created: false };
+        return { folder, name: pluginManifestName(folder), created: false };
       }
       try {
         await this.provision(user, folder, personalAccessMd(user));
@@ -177,11 +215,11 @@ export class PluginProvisionService {
         // process, a checkout that appeared between check and write): the
         // folder existing is this method's success case, never its error.
         if (err instanceof PluginProvisionError && err.status === 409) {
-          return { folder, created: false };
+          return { folder, name: pluginManifestName(folder), created: false };
         }
         throw err;
       }
-      return { folder, created: true };
+      return { folder, name: pluginManifestName(folder), created: true };
     });
   }
 
@@ -204,29 +242,64 @@ export class PluginProvisionService {
    * never interleave with a re-creation of the same name (the key derives
    * from the name, so both spell it identically).
    */
-  async deletePlugin(user: AuthUser, rawName: string): Promise<void> {
-    const name = rawName.trim();
-    if (!name) throw new PluginProvisionError('A plugin needs a name.', 422);
-    if (isPersonalPluginFolder(name)) {
+  async deletePlugin(user: AuthUser, rawFolder: string): Promise<void> {
+    // The folder's path BELOW the plugins root — `GTM`, or `teams/deep` for a
+    // plugin nested where discovery found it. Segments only: nothing that
+    // could climb out of the root, and no backslash — `/` is the one
+    // separator the repository speaks, and a `\` would read as a second one
+    // on Windows and as a name character everywhere else.
+    // Validated AS GIVEN, never trimmed first: a folder spelled with a
+    // leading or trailing space names no folder the catalog handed out, and
+    // trimming it would delete a different one. (`validateFilename` refuses
+    // the whitespace.)
+    const name = rawFolder;
+    const segments = name.split('/');
+    // Every segment must be a name the filesystem carries (the ONE rule
+    // creation applies, `validateFilename`: no control characters, no `\`,
+    // no `.`/`..`, no reserved names) and none may be dot-prefixed (a parked
+    // delete, invisible to every scanner) — refused here as a 422, never
+    // discovered by the fs layer as a 500.
+    if (!name || segments.some((s) => validateFilename(s) !== null || s.startsWith('.'))) {
+      throw new PluginProvisionError('A plugin needs a name.', 422);
+    }
+    if (isPersonalPluginDir(`${PLUGINS_DIR}/${name}`)) {
       // Personal folders are not plugins (the catalog never lists them), and
       // nobody deletes somebody's private shelf through the plugin door.
       throw new PluginProvisionError('Unknown plugin', 404);
     }
-    return this.creations.run(`plugin:${pluginManifestName(name)}`, async () => {
-      const existing = await this.existingFolder(name);
-      // Exact match only — the catalog hands the route the on-disk casing,
-      // so a mismatch means the plugin is gone (or was never there).
-      if (existing !== name) throw new PluginProvisionError('Unknown plugin', 404);
+    const wsId = await this.readyWorkspaceId();
+    const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+    const pluginsDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR);
+    const folderDir = path.join(pluginsDir, ...segments);
+    // Locked on the plugin's IDENTITY — the same key a creation of that name
+    // takes — not on a slug of the folder path, which for a nested plugin is a
+    // different string and would let a creation of the same identity run
+    // inside the delete's window. The identity is DISCOVERY's answer, in
+    // either file shape (a bundle's name as much as a manifest's), so delete
+    // and create can never key on two spellings of one plugin; a hole in
+    // discovery refuses, as it does for creation. A folder discovery does not
+    // list (no manifest at all) locks on its own slug — nothing else can
+    // claim that identity either.
+    const identity = await this.discoveredIdentity(`${PLUGINS_DIR}/${name}`, segments[segments.length - 1]!);
+    return this.creations.run(`plugin:${identity}`, async () => {
+      // Exact spelling of EVERY component — the catalog hands the route the
+      // on-disk spelling, so a mismatch means the plugin is gone (or was
+      // never there). Checked against directory listings, never `stat`: on a
+      // case-insensitive filesystem a stale spelling would stat a replacement
+      // plugin at the same location and park THAT.
+      if (!(await this.exactFolderExists(pluginsDir, segments))) {
+        throw new PluginProvisionError('Unknown plugin', 404);
+      }
 
-      const wsId = await this.readyWorkspaceId();
-      const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-      const pluginsDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR);
-      const folderDir = path.join(pluginsDir, name);
       // Dot-prefixed ⇒ invisible to the plugin scanner and the collision
-      // check for the whole window the commit is in flight.
-      const parkedDir = path.join(pluginsDir, `.${name}.deleting`);
-
-      await fs.rm(parkedDir, { recursive: true, force: true }); // a stale park from a crashed run
+      // check for the whole window the commit is in flight. UNIQUE, so the
+      // park never lands on — and never removes — a path that was already
+      // there: a sibling somebody named that way, or the residue of a run
+      // that crashed mid-delete (which stays, invisible, for a person to
+      // clear; a delete must never destroy anything but the plugin it names).
+      // FIXED LENGTH: the plugin's own name is not part of it, so a name near
+      // the filesystem's component limit parks as well as a short one.
+      const parkedDir = path.join(path.dirname(folderDir), `.deleting-${randomUUID()}`);
       await fs.rename(folderDir, parkedDir);
       try {
         // Inline and `systemAuthorized`, for `provision`'s reasons in
@@ -261,45 +334,78 @@ export class PluginProvisionService {
     });
   }
 
+  /**
+   * Whether `segments` names a directory below `root` with every component
+   * spelled exactly as on disk — by listing each level, which is the one
+   * question a case-insensitive filesystem answers honestly.
+   */
+  private async exactFolderExists(root: string, segments: string[]): Promise<boolean> {
+    let dir = root;
+    let rel = PLUGINS_DIR;
+    for (const segment of segments) {
+      const entries = await listDirOrIncomplete(dir, rel);
+      if (!entries?.some((e) => e.isDirectory() && e.name === segment)) return false;
+      dir = path.join(dir, segment);
+      rel = `${rel}/${segment}`;
+    }
+    return true;
+  }
+
   /** The taken name (in its on-disk casing) colliding with `name`, or null. */
   private async existingFolder(name: string): Promise<string | null> {
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    let children: string[];
-    try {
-      children = await fs.readdir(path.join(wsDir, this.kbDirName, PLUGINS_DIR));
-    } catch {
-      return null; // no Plugins/ root yet — nothing can collide
-    }
+    // No Plugins/ root yet — nothing can collide.
+    const children = await listDirOrIncomplete(path.join(wsDir, this.kbDirName, PLUGINS_DIR), PLUGINS_DIR);
+    if (!children) return null;
     const lower = name.toLowerCase();
-    return children.find((c) => c.toLowerCase() === lower) ?? null;
+    return children.find((c) => c.name.toLowerCase() === lower)?.name ?? null;
   }
 
-  /** An existing PLUGIN FOLDER whose derived manifest name equals `name`'s, or null. */
-  private async manifestNameTwin(name: string): Promise<string | null> {
+  /**
+   * The identity discovery gives the plugin at `folder`, or the folder's own
+   * slug when it lists none there. ONE rule for every write provisioning
+   * makes — create, delete — as for the rename: no write over a discovery
+   * with a hole in it, whether or not the hole is where this plugin lives.
+   * An operation that parks and commits against an identity set it could
+   * not fully see is the class of mistake the rule exists to make impossible.
+   */
+  private async discoveredIdentity(folder: string, leaf: string): Promise<string> {
+    const { plugins, unreadable } = await this.discovered();
+    if (unreadable.length > 0) throw incompleteDiscovery(unreadable);
+    const found = plugins.find((p) => p.folder === folder);
+    // The lock key is the SLUG — what the marketplace publishes and what a
+    // creation of the name locks on — so a bundle declaring "Sales Team"
+    // and a creation of `sales-team` take one lock. Not listed and nothing
+    // unreadable: no manifest, no bundle — the folder is its own identity.
+    return pluginManifestName(found ? found.name : leaf);
+  }
+
+  /** One discovery over the knowledge base checkout. */
+  private async discovered(): Promise<Discovery> {
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    let children: Array<{ name: string; isDirectory(): boolean }>;
-    try {
-      children = await fs.readdir(path.join(wsDir, this.kbDirName, PLUGINS_DIR), {
-        withFileTypes: true,
-      });
-    } catch {
-      return null; // no Plugins/ root yet — nothing can collide
-    }
+    return this.source.discover(path.join(wsDir, this.kbDirName));
+  }
+
+  /**
+   * An existing plugin — at ANY depth, in either file shape — whose identity
+   * folds to the same slug as `name`'s, as its repo-relative folder; or null.
+   * Discovery's answer, so creation and every catalog agree on what is taken:
+   * a nested plugin claims its identity as fully as a top-level one, and a
+   * parked delete (dot-prefixed, invisible to the walk) claims nothing.
+   * Personal folders count — they publish a plugin.json like any plugin
+   * (though the reservation above means a named plugin never reaches this
+   * check with a personal slug). A loose file at the root is not a plugin.
+   *
+   * Refuses on a HOLE: a listing that could not see part of the tree cannot
+   * prove a name free.
+   */
+  private async manifestNameTwin(name: string): Promise<string | null> {
+    const { plugins, unreadable } = await this.discovered();
+    if (unreadable.length > 0) throw incompleteDiscovery(unreadable);
     const slug = pluginManifestName(name);
-    // Only what actually publishes a manifest claims a slug: a DIRECTORY
-    // that is not dot-prefixed (a parked delete — invisible to every
-    // scanner). Personal folders count — they publish a plugin.json like
-    // any plugin (though the reservation above means a named plugin can
-    // never reach this check with a personal slug). A loose file at the
-    // root (`Plugins/slack.tool`) is not a plugin and must not 409 a
-    // legitimate "Slack Tool".
-    return (
-      children.find(
-        (c) => c.isDirectory() && !c.name.startsWith('.') && pluginManifestName(c.name) === slug,
-      )?.name ?? null
-    );
+    return plugins.find((p) => pluginManifestName(p.name) === slug)?.folder ?? null;
   }
 
   private async provision(user: AuthUser, folder: string, accessMd: string): Promise<void> {

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

@@ -0,0 +1,298 @@
+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 { walkKb, type KbWalkListener } from '../../shared/kb-walk.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 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: KbWalkListener = {
+      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 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' });
+    }
+    const folderName = path.posix.basename(plugin.folder);
+    const nextDisplay =
+      patch.displayName === undefined ? plugin.displayName : String(patch.displayName).trim();
+
+    // The manifest, with everything else in it kept.
+    const manifest: Record<string, unknown> = { ...(plugin.manifest ?? {}), name: nextName };
+    if (nextDisplay && nextDisplay !== folderName) manifest.displayName = nextDisplay;
+    else delete manifest.displayName;
+    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);
+    return {
+      name: nextName,
+      displayName: pluginDisplayNameOf(manifest, folderName),
+      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,14 @@ 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[];
+  /** 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,6 +77,16 @@ 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;
@@ -90,10 +106,21 @@ 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 the folder name. */
+  displayName: string;
   folders: 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;