@bevel-software/platform-core-backend 0.7.5 → 0.8.0

package/src/modules/{groups/group-provision.service.ts → plugins/plugin-provision.service.ts}

@@ -1,13 +1,13 @@
 /**
- * Group provisioning — the ONE privileged door for bringing a `Groups/<name>/`
- * folder into existence, and (via {@link GroupProvisionService.deleteGroup})
+ * Plugin provisioning — the ONE privileged door for bringing a `Plugins/<name>/`
+ * folder into existence, and (via {@link PluginProvisionService.deletePlugin})
  * for taking one back out of it.
  *
- * Creating a group is the single operation the access model cannot govern
+ * Creating a plugin is the single operation the access model cannot govern
  * from inside: the folder that will carry the rules does not exist yet, and
  * the root's own rule (`write: Admin`) says no. The old answer was a
  * carve-out inside the generic write gate — every write path could claim an
- * unused name under `Groups/`, and the gate had to re-derive "is this that
+ * unused name under `Plugins/`, and the gate had to re-derive "is this that
  * one blessed case?" on every check. This service replaces that: the generic
  * gate is uniformly strict again, and the privilege lives here, named,
  * behind its own endpoint.
@@ -21,8 +21,8 @@
  *
  * Two shapes, two templates:
  *
- *   - A NAMED group: discoverable by design. The access.md's own frontmatter
- *     reads `everyone` — anyone may open the FILE, see the group listed, and
+ *   - A NAMED plugin: discoverable by design. The access.md's own frontmatter
+ *     reads `everyone` — anyone may open the FILE, see the plugin listed, and
  *     ask to join — while the BODY (the folder's actual rules) names only
  *     the creator under read, write and owner.
  *   - A PERSONAL folder (`personal-<user-id>`): private by design. No
@@ -36,10 +36,13 @@ import path from 'node:path';
 
 import {
   DEFAULT_BRANCH,
-  GROUPS_DIR,
-  PERSONAL_GROUP_PREFIX,
-  isPersonalGroupFolder,
-  personalGroupFolderName,
+  PLUGINS_DIR,
+  PLUGIN_MANIFEST_FILE,
+  pluginManifestName,
+  renderPluginManifest,
+  PERSONAL_PLUGIN_PREFIX,
+  isPersonalPluginFolder,
+  personalPluginFolderName,
   type AuthUser,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -59,31 +62,32 @@ export interface ProvisionCommitDriver {
   ): Promise<void>;
 }
 
-export interface ProvisionedGroup {
-  /** The folder name under `Groups/` (not the full path). */
+export interface ProvisionedPlugin {
+  /** The folder name under `Plugins/` (not the full path). */
   folder: string;
   /** False when an ensure found the folder already there. */
   created: boolean;
 }
 
 /** A refusal the route can pass through: message + HTTP status. */
-export class GroupProvisionError extends Error {
+export class PluginProvisionError extends Error {
   constructor(
     message: string,
     readonly status: number,
   ) {
     super(message);
-    this.name = 'GroupProvisionError';
+    this.name = 'PluginProvisionError';
   }
 }
 
-export class GroupProvisionService {
+export class PluginProvisionService {
   /**
-   * Serialises creations by NORMALIZED (lowercased) folder name. The wx write
-   * arbitrates same-path races, but on a case-sensitive filesystem `GTM` and
-   * `gtm` are different paths — without this lock two concurrent requests
-   * could both pass the collision check and both land, breaking the
-   * case-insensitive uniqueness the check promises.
+   * Serialises creations and deletions by MANIFEST SLUG
+   * (`pluginManifestName(name)`). The wx write arbitrates same-path races,
+   * but the identity the collision checks defend is the slug: case-variants
+   * (`GTM`/`gtm`) and distinct spellings (`Sales Team`/`Sales-Team`) all
+   * derive the same key, so no two requests that would publish one manifest
+   * name can hold the lock at once.
    */
   private readonly creations = new WorkspaceMutex();
 
@@ -96,37 +100,62 @@ export class GroupProvisionService {
   ) {}
 
   /**
-   * Create `Groups/<name>/` for `user`. Throws `GroupProvisionError` 422 on a
+   * Create `Plugins/<name>/` for `user`. Throws `PluginProvisionError` 422 on a
    * name the filesystem or the model cannot carry, 409 when the name is taken
    * (case-insensitively — the workspaces live on case-insensitive
    * filesystems too, where `GTM` and `gtm` are one folder).
    */
-  async createGroup(user: AuthUser, rawName: string): Promise<ProvisionedGroup> {
+  async createPlugin(user: AuthUser, rawName: string): Promise<ProvisionedPlugin> {
     const name = rawName.trim();
-    if (!name) throw new GroupProvisionError('A group needs a name.', 422);
+    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.
     if (/[/\\\u0000-\u001f\u007f]/.test(name) || name === '.' || name === '..' || name.startsWith('.')) {
-      throw new GroupProvisionError(
-        'A group name can\'t contain / or \\ or control characters, or start with a dot.',
+      throw new PluginProvisionError(
+        'A plugin name can\'t contain / or \\ or control characters, or start with a dot.',
         422,
       );
     }
-    if (name.toLowerCase().startsWith(PERSONAL_GROUP_PREFIX)) {
-      // Reserved: the personal-folder namespace. A group squatting there
-      // would collide with somebody's future personal folder.
-      throw new GroupProvisionError(
-        `Group names starting with "${PERSONAL_GROUP_PREFIX}" are reserved.`,
+    // Reserved BY SLUG, which subsumes the folder-name spelling: personal
+    // folders publish manifests like any plugin, so "Personal Abc" (slug
+    // `personal-abc`) squats the namespace exactly as "personal-abc" would —
+    // a name-only check let it through.
+    if (pluginManifestName(name).startsWith(PERSONAL_PLUGIN_PREFIX)) {
+      // The message names the DERIVED slug: for a spelling like "Personal
+      // Abc" the reservation is invisible in the name itself, and a refusal
+      // the user can't trace to their input is a refusal they can't fix.
+      throw new PluginProvisionError(
+        `"${name}" would publish the manifest name "${pluginManifestName(name)}" — ` +
+          `the "${PERSONAL_PLUGIN_PREFIX}" namespace is reserved for personal folders. Pick another name.`,
         422,
       );
     }
-    return this.creations.run(`group:${name.toLowerCase()}`, async () => {
+    // Locked on the manifest SLUG, not the lowercased folder: the slug is the
+    // identity the twin check below defends, and two spellings that collide
+    // on it ("Sales Team" / "Sales-Team") must take the SAME lock or both
+    // pass the check concurrently. Case-variants share a slug too, so this
+    // key subsumes the old lowercase one — and deletion (below) derives its
+    // key the same way, keeping delete/re-create of one name serialized.
+    return this.creations.run(`plugin:${pluginManifestName(name)}`, async () => {
       const existing = await this.existingFolder(name);
       if (existing !== null) {
-        throw new GroupProvisionError(`A group named "${existing}" already exists.`, 409);
+        throw new PluginProvisionError(`A plugin named "${existing}" already exists.`, 409);
       }
-      await this.provision(user, name, groupAccessMd(user));
+      // Folder uniqueness is not manifest uniqueness: the manifest `name` is
+      // a LOSSY slug of the folder (`Sales Team` and `Sales-Team` both
+      // become `sales-team`), and it is the identity a conformant client
+      // keys plugins on — two folders sharing it would be two plugins one
+      // key, with no telling which a client resolves.
+      const slugTwin = await this.manifestNameTwin(name);
+      if (slugTwin !== null) {
+        throw new PluginProvisionError(
+          `"${name}" and the existing plugin "${slugTwin}" would share the manifest name ` +
+            `"${pluginManifestName(name)}" — pick a more distinct name.`,
+          409,
+        );
+      }
+      await this.provision(user, name, pluginAccessMd(user));
       return { folder: name, created: true };
     });
   }
@@ -135,9 +164,9 @@ export class GroupProvisionService {
    * Ensure the caller's personal folder exists — idempotent, keyed to the
    * stable user id. Returns `created: false` when it is already there.
    */
-  async ensurePersonalGroup(user: AuthUser): Promise<ProvisionedGroup> {
-    const folder = personalGroupFolderName(user.id);
-    return this.creations.run(`group:${folder.toLowerCase()}`, async () => {
+  async ensurePersonalPlugin(user: AuthUser): Promise<ProvisionedPlugin> {
+    const folder = personalPluginFolderName(user.id);
+    return this.creations.run(`plugin:${pluginManifestName(folder)}`, async () => {
       if ((await this.existingFolder(folder)) !== null) {
         return { folder, created: false };
       }
@@ -147,7 +176,7 @@ export class GroupProvisionService {
         // ENSURE semantics even under a race the lock cannot see (another
         // process, a checkout that appeared between check and write): the
         // folder existing is this method's success case, never its error.
-        if (err instanceof GroupProvisionError && err.status === 409) {
+        if (err instanceof PluginProvisionError && err.status === 409) {
           return { folder, created: false };
         }
         throw err;
@@ -157,10 +186,10 @@ export class GroupProvisionService {
   }
 
   /**
-   * Delete `Groups/<name>/` — the whole folder, its skills and tools
+   * Delete `Plugins/<name>/` — the whole folder, its skills and tools
    * included, in ONE commit. MECHANISM only: the route owns the
    * authorization (the caller must hold the `owner` verb on the folder;
-   * this service never re-derives it), exactly as `createGroup` leaves
+   * this service never re-derives it), exactly as `createPlugin` leaves
    * "any signed-in user" to its endpoint.
    *
    * Shape mirrors a provision run in reverse, with the same failure
@@ -168,33 +197,34 @@ export class GroupProvisionService {
    * scanners ignore) rather than removed, the deletion is committed
    * synchronously, and only a landed commit lets the parked bytes go. A
    * refused commit renames the folder back, so a failed delete leaves the
-   * group exactly as it was — never half-gone on disk while origin still
+   * plugin exactly as it was — never half-gone on disk while origin still
    * carries it.
    *
-   * Serialised on the same per-name lock creations use, so a delete can
-   * never interleave with a re-creation of the same name.
+   * Serialised on the same slug-keyed lock creations use, so a delete can
+   * never interleave with a re-creation of the same name (the key derives
+   * from the name, so both spell it identically).
    */
-  async deleteGroup(user: AuthUser, rawName: string): Promise<void> {
+  async deletePlugin(user: AuthUser, rawName: string): Promise<void> {
     const name = rawName.trim();
-    if (!name) throw new GroupProvisionError('A group needs a name.', 422);
-    if (isPersonalGroupFolder(name)) {
-      // Personal folders are not groups (the catalog never lists them), and
-      // nobody deletes somebody's private shelf through the group door.
-      throw new GroupProvisionError('Unknown group', 404);
+    if (!name) throw new PluginProvisionError('A plugin needs a name.', 422);
+    if (isPersonalPluginFolder(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(`group:${name.toLowerCase()}`, async () => {
+    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 group is gone (or was never there).
-      if (existing !== name) throw new GroupProvisionError('Unknown group', 404);
+      // 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 groupsDir = path.join(wsDir, this.kbDirName, GROUPS_DIR);
-      const folderDir = path.join(groupsDir, name);
-      // Dot-prefixed ⇒ invisible to the group scanner and the collision
+      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(groupsDir, `.${name}.deleting`);
+      const parkedDir = path.join(pluginsDir, `.${name}.deleting`);
 
       await fs.rm(parkedDir, { recursive: true, force: true }); // a stale park from a crashed run
       await fs.rename(folderDir, parkedDir);
@@ -205,17 +235,17 @@ export class GroupProvisionService {
         // push gate — which would re-read an access.md this very commit
         // removes — is skipped for exactly this commit. `commitFile` is
         // path-scoped (`git add -- <path>`), and a folder path stages every
-        // deletion under it: one commit, one removed group.
+        // deletion under it: one commit, one removed plugin.
         await this.commits.runPendingCommit(
           wsId,
           DEFAULT_BRANCH,
-          `${this.kbDirName}/${GROUPS_DIR}/${name}`,
+          `${this.kbDirName}/${PLUGINS_DIR}/${name}`,
           user,
           { systemAuthorized: true },
         );
       } catch (err) {
         // The commit did not land: put the folder back, so a failed delete
-        // is a no-op rather than a group that exists at origin but not here.
+        // is a no-op rather than a plugin that exists at origin but not here.
         try {
           await fs.rename(parkedDir, folderDir);
         } catch {
@@ -237,28 +267,67 @@ export class GroupProvisionService {
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
     let children: string[];
     try {
-      children = await fs.readdir(path.join(wsDir, this.kbDirName, GROUPS_DIR));
+      children = await fs.readdir(path.join(wsDir, this.kbDirName, PLUGINS_DIR));
     } catch {
-      return null; // no Groups/ root yet — nothing can collide
+      return null; // no Plugins/ root yet — nothing can collide
     }
     const lower = name.toLowerCase();
     return children.find((c) => c.toLowerCase() === lower) ?? null;
   }
 
+  /** An existing PLUGIN FOLDER whose derived manifest name equals `name`'s, or null. */
+  private async manifestNameTwin(name: string): Promise<string | null> {
+    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
+    }
+    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
+    );
+  }
+
   private async provision(user: AuthUser, folder: string, accessMd: string): Promise<void> {
     const wsId = await this.readyWorkspaceId();
-    const wsRelPath = `${this.kbDirName}/${GROUPS_DIR}/${folder}/access.md`;
+    const folderPath = `${this.kbDirName}/${PLUGINS_DIR}/${folder}`;
+    const wsRelPath = `${folderPath}/access.md`;
     try {
       // Exclusive create — the fs is the arbiter of a same-name race, not
-      // the (stale-able) existence check above.
+      // the (stale-able) existence check above. `access.md` stays the marker
+      // that a folder is real (every scanner keys on it), so it is still the
+      // file the race is decided on.
       await this.workspaceService.writeFile(wsId, wsRelPath, accessMd, { failIfExists: true });
     } catch (err) {
       if ((err as { status?: number }).status === 409) {
-        throw new GroupProvisionError(`A group named "${folder}" already exists.`, 409);
+        throw new PluginProvisionError(`A plugin named "${folder}" already exists.`, 409);
       }
       throw err;
     }
     try {
+      // The manifest is what makes the folder a PLUGIN to anything outside
+      // this app, so it lands in the same commit as the access rules — and
+      // INSIDE the rollback scope: a manifest write that fails must clean up
+      // the access.md it would otherwise strand as a half-made plugin.
+      await this.workspaceService.writeFile(
+        wsId,
+        `${folderPath}/${PLUGIN_MANIFEST_FILE}`,
+        renderPluginManifest(folder),
+      );
       // Inline, not enqueued: the gate reads rules at HEAD, so the folder is
       // only real once this commit lands. `runPendingCommit` is the same
       // commit+push (with pull-rebase recovery) the queue worker runs.
@@ -267,19 +336,20 @@ export class GroupProvisionService {
       // rule this endpoint exists to carve through. The endpoint has already
       // authorized the write (any signed-in user, unused name, exclusive
       // create), so the per-user gate is skipped for exactly this commit.
-      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, wsRelPath, user, {
+      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, folderPath, user, {
         systemAuthorized: true,
       });
     } catch (err) {
       // The commit did not land: roll the seeded file back off the disk,
-      // best-effort, so a retry doesn't find a half-made group and report
+      // best-effort, so a retry doesn't find a half-made plugin and report
       // "already exists" for something that never got committed. Only OUR
       // file and — when that leaves it empty — the folder; never recursive,
       // so a concurrent writer's bytes can't be collateral.
       try {
         const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-        const folderDir = path.join(wsDir, this.kbDirName, GROUPS_DIR, folder);
+        const folderDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR, folder);
         await fs.rm(path.join(folderDir, 'access.md'), { force: true });
+        await fs.rm(path.join(folderDir, PLUGIN_MANIFEST_FILE), { force: true });
         await fs.rmdir(folderDir).catch(() => {});
       } catch {
         /* leave it for the next attempt's wx conflict — better than masking the real error */
@@ -299,13 +369,13 @@ export class GroupProvisionService {
 }
 
 /**
- * A named group's access.md: discoverable file (frontmatter `read: everyone`
- * — anyone may see the group listed and ask to join), creator-run folder
+ * A named plugin's access.md: discoverable file (frontmatter `read: everyone`
+ * — anyone may see the plugin listed and ask to join), creator-run folder
  * (body read/write/owner name the creator). The `read: []` placeholder makes
  * the body parse as rules from the first byte, so every later splice targets
  * the body rather than the frontmatter.
  */
-export function groupAccessMd(creator: { name: string; email: string }): string {
+export function pluginAccessMd(creator: { name: string; email: string }): string {
   return withCreatorGrants('---\nread:\n  - everyone\n---\nread: []\n', creator);
 }
 

package/src/modules/{groups/groups.contract.ts → plugins/plugins.contract.ts}

@@ -1,16 +1,16 @@
 /**
- * Groups — the folders under `Groups/` that carry a team's skills and the
- * tools those skills need. A group is a FOLDER, never a role: one access
- * boundary, one place, derived from the path exactly the way `groupOfPath`
+ * Plugins — the folders under `Plugins/` that carry a team's skills and the
+ * tools those skills need. A plugin is a FOLDER, never a role: one access
+ * boundary, one place, derived from the path exactly the way `pluginOfPath`
  * derives it.
  *
- * A group EXISTS exactly when its folder carries an `access.md` — the file
- * the provisioning endpoint seeds. A bare directory under `Groups/` is not a
- * group (git cannot record an empty folder, so deleted groups leave ghost
+ * A plugin EXISTS exactly when its folder carries an `access.md` — the file
+ * the provisioning endpoint seeds. A bare directory under `Plugins/` is not a
+ * plugin (git cannot record an empty folder, so deleted plugins leave ghost
  * directories on live checkouts).
  *
  * Enumeration then follows the KB's read model with NO special cases: an
- * existing group appears for a caller exactly when the access resolution says
+ * existing plugin appears for a caller exactly when the access resolution says
  * something about it —
  *
  *   - MEMBER: the caller can read the folder itself (`canRead`).
@@ -18,11 +18,11 @@
  *     admin-rescued).
  *   - DISCOVERABLE: the caller can read the `access.md` FILE — which, in the
  *     new body-governed format, is granted by the file's own
- *     `read: everyone` frontmatter (see `accessMdSelfEntries`). The group
+ *     `read: everyone` frontmatter (see `accessMdSelfEntries`). The plugin
  *     shows locked, and the caller may ask to join.
  *
- * A group where all three verdicts are false is ABSENT from the response —
- * name, counts and principals never leave the backend. Making a group secret
+ * A plugin where all three verdicts are false is ABSENT from the response —
+ * name, counts and principals never leave the backend. Making a plugin secret
  * is therefore an ordinary access edit: drop the `everyone` grant from its
  * access.md frontmatter.
  *
@@ -43,32 +43,32 @@ export interface ResolvedReaders extends ResolvedPrincipals {
   restricted: boolean;
 }
 
-/** One group as `GET /api/groups` reports it, resolved for ONE caller. */
-export interface GroupSummary {
-  /** Group folder name, e.g. `GTM`. */
+/** One plugin as `GET /api/plugins` reports it, resolved for ONE caller. */
+export interface PluginSummary {
+  /** Plugin folder name, e.g. `GTM`. */
   name: string;
-  /** Repo-relative constituent folders, e.g. `['Groups/GTM']`. */
+  /** Repo-relative constituent folders, e.g. `['Plugins/GTM']`. */
   folders: string[];
   /**
    * Per-caller: the caller can read the FOLDER (membership). Every returned
-   * group has at least one of `canRead` / `canWrite` / discoverability; a
-   * group with none is not returned at all.
+   * plugin has at least one of `canRead` / `canWrite` / discoverability; a
+   * plugin with none is not returned at all.
    */
   canRead: boolean;
   /**
    * Per-caller; true ⇒ may manage access. Resolved as write on the folder's
    * `access.md`, which admin-rescues — so a platform Admin locked OUT of
-   * reading still sees the group and gets the self-service way back in.
+   * reading still sees the plugin and gets the self-service way back in.
    */
   canWrite: boolean;
   /**
    * Per-caller: the caller holds the `owner` verb on the FOLDER — resolved
-   * from the `owner:` lists alone, no admin rescue. Deleting the group is the
+   * from the `owner:` lists alone, no admin rescue. Deleting the plugin is the
    * owner's verb (the DELETE route enforces the same verdict); managers who
    * merely write the access.md do not get it.
    */
   isOwner: boolean;
-  /** Caller-INDEPENDENT total (the group's whole content, not the caller's slice). */
+  /** Caller-INDEPENDENT total (the plugin's whole content, not the caller's slice). */
   skillCount: number;
   toolCount: number;
   /** For display: "Run by …" (fallback chain: owners → writers → 'the workspace admins'). */
@@ -76,7 +76,7 @@ export interface GroupSummary {
   writers: ResolvedPrincipals;
   readers: ResolvedReaders;
   /**
-   * The caller has an OPEN join change request for this group (their
+   * The caller has an OPEN join change request for this plugin (their
    * deterministic join branch has an open CR). Always false for a member.
    */
   hasRequested: boolean;
@@ -85,11 +85,11 @@ export interface GroupSummary {
 }
 
 /**
- * The caller-INDEPENDENT slice of a group — what `catalog()` computes once and
- * caches. The per-caller verdicts (`canRead`/`canWrite`, and whether the group
+ * The caller-INDEPENDENT slice of a plugin — what `catalog()` computes once and
+ * caches. The per-caller verdicts (`canRead`/`canWrite`, and whether the plugin
  * appears at all) are resolved per request in the route.
  */
-export interface GroupCatalogEntry {
+export interface PluginCatalogEntry {
   name: string;
   folders: string[];
   skillCount: number;
@@ -99,9 +99,9 @@ export interface GroupCatalogEntry {
   readers: ResolvedReaders;
 }
 
-export interface IGroupIndexService {
+export interface IPluginIndexService {
   /** Caller-independent catalog part (folders, counts, principals) — cached 60s. */
-  catalog(): Promise<GroupCatalogEntry[]>;
-  /** Drop the cached catalog (call after a default-branch change under a group root). */
+  catalog(): Promise<PluginCatalogEntry[]>;
+  /** Drop the cached catalog (call after a default-branch change under a plugin root). */
   invalidate(): void;
 }