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

package/dist/modules/plugins/plugin-rename.service.js

@@ -0,0 +1,245 @@
+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 { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
+import { walkKb } from '../../shared/kb-walk.js';
+import { PLUGIN_TOKEN_PREFIX, canonicalPluginToken, hasAccessFrontmatterExtension, parsePluginPrincipalKey, } from '../access-model/access-grammar.js';
+import { linksWorkspaceId } from './plugin-links.js';
+export class PluginRenameError extends Error {
+    status;
+    payload;
+    constructor(message, status, payload = {}) {
+        super(message);
+        this.status = status;
+        this.payload = payload;
+        this.name = 'PluginRenameError';
+    }
+}
+/**
+ * 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 {
+    workspaceService;
+    commits;
+    accessControl;
+    source;
+    kbDirName;
+    events;
+    onChanged;
+    constructor(workspaceService, commits, accessControl, source, kbDirName, events, onChanged) {
+        this.workspaceService = workspaceService;
+        this.commits = commits;
+        this.accessControl = accessControl;
+        this.source = source;
+        this.kbDirName = kbDirName;
+        this.events = events;
+        this.onChanged = onChanged;
+    }
+    noteChanged(wsId) {
+        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. */
+    assertComplete(unreadable) {
+        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, current, patch) {
+        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 = [];
+        const grantListener = {
+            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 = { ...(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: 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 = [];
+            for (const rel of grantFiles) {
+                const abs = path.join(kbRoot, rel);
+                let before;
+                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 = [];
+            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, events, onChanged, wsId) {
+    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, oldName, nextName) {
+    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() {
+    // The default branch's workspace id IS its encoded branch name.
+    return decodeURIComponent(linksWorkspaceId());
+}
+//# sourceMappingURL=plugin-rename.service.js.map

package/dist/modules/plugins/plugin-rename.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-rename.service.js","sourceRoot":"","sources":["../../../src/modules/plugins/plugin-rename.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/plugins/plugins.contract.d.ts

@@ -32,6 +32,7 @@
  * via Manage access, which makes the CR moot). To agents these are plain
  * 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 +46,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 +76,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;
@@ -89,10 +104,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;

package/dist/modules/plugins/plugins.contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugins.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,OAAO,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,wFAAwF;IACxF,UAAU,IAAI,IAAI,CAAC;CACpB"}
+{"version":3,"file":"plugins.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugins.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,OAAO,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,wFAAwF;IACxF,UAAU,IAAI,IAAI,CAAC;CACpB"}

package/dist/modules/plugins/plugins.routes.d.ts

@@ -4,6 +4,8 @@ import { type AuthUser, type IWorkflowService } from '@bevel-software/platform-s
 import type { IAccessControl } from '../access/access-control.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { type PluginProvisionService } from './plugin-provision.service.js';
+import { type PluginLinksService } from './plugin-links.service.js';
+import { type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
 import type { IPluginIndexService } from './plugins.contract.js';
 /**
@@ -38,5 +40,9 @@ import type { IPluginIndexService } from './plugins.contract.js';
  * middleware change can never silently un-gate one. Nothing here is reachable
  * with an agent connection key or a manual-auth bearer.
  */
-export declare function createPluginsRoutes(pluginIndex: IPluginIndexService, accessControl: IAccessControl, workflow: IWorkflowService, workspaceService: WorkspaceService, joinRequests: JoinRequestsService, provision: PluginProvisionService, kbDirName: string, resolveUser: (req: express.Request) => Promise<AuthUser | null>): express.Router;
+export declare function createPluginsRoutes(pluginIndex: IPluginIndexService, accessControl: IAccessControl, workflow: IWorkflowService, workspaceService: WorkspaceService, joinRequests: JoinRequestsService, provision: PluginProvisionService, kbDirName: string, resolveUser: (req: express.Request) => Promise<AuthUser | null>, 
+/** Optional: a host without the link machinery simply has no link routes. */
+links?: PluginLinksService, 
+/** Optional: a host without it has no rename route. */
+rename?: PluginRenameService): express.Router;
 //# sourceMappingURL=plugins.routes.d.ts.map

package/dist/modules/plugins/plugins.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugins.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,QAAQ,EAEb,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAG5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAClG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,mBAAmB,EAChC,aAAa,EAAE,cAAc,EAC7B,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,mBAAmB,EACjC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAC9D,OAAO,CAAC,MAAM,CAiXhB"}
+{"version":3,"file":"plugins.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugins.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,QAAQ,EAEb,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAG5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAClG,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,mBAAmB,EAChC,aAAa,EAAE,cAAc,EAC7B,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,mBAAmB,EACjC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC/D,6EAA6E;AAC7E,KAAK,CAAC,EAAE,kBAAkB;AAC1B,uDAAuD;AACvD,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAgehB"}

package/dist/modules/plugins/plugins.routes.js

@@ -5,6 +5,8 @@ import { spliceGrant } from '../access-model/access-splice.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { pluginsWorkspaceId } from './plugins.service.js';
 import { PluginProvisionError } from './plugin-provision.service.js';
+import { PluginLinkError } from './plugin-links.service.js';
+import { PluginRenameError } from './plugin-rename.service.js';
 /**
  * Browser-facing (JWT) plugin routes, mounted behind `authMiddleware`:
  *
@@ -37,12 +39,111 @@ import { PluginProvisionError } from './plugin-provision.service.js';
  * middleware change can never silently un-gate one. Nothing here is reachable
  * with an agent connection key or a manual-auth bearer.
  */
-export function createPluginsRoutes(pluginIndex, accessControl, workflow, workspaceService, joinRequests, provision, kbDirName, resolveUser) {
+export function createPluginsRoutes(pluginIndex, accessControl, workflow, workspaceService, joinRequests, provision, kbDirName, resolveUser, 
+/** Optional: a host without the link machinery simply has no link routes. */
+links, 
+/** Optional: a host without it has no rename route. */
+rename) {
     const router = express.Router();
+    /**
+     * Rename a plugin — its identifier, its display name, or both. The
+     * MANAGER's verb (write on the folder's access.md, the gate linking uses).
+     * An identifier change rewrites every grant naming the old identifier in
+     * the same commit; see `PluginRenameService`.
+     *
+     *   PATCH /api/plugins/:name  { name?, displayName? }  → { name, displayName, rewritten }
+     */
+    if (rename) {
+        router.patch('/plugins/:name', async (req, res) => {
+            if (!req.userEmail) {
+                res.status(401).json({ error: 'Unauthenticated' });
+                return;
+            }
+            const user = await resolveUser(req);
+            if (!user) {
+                res.status(401).json({ error: 'Unauthenticated' });
+                return;
+            }
+            const body = (req.body ?? {});
+            try {
+                res.json(await rename.rename(user, String(req.params.name), { name: body.name, displayName: body.displayName }));
+            }
+            catch (err) {
+                if (err instanceof PluginRenameError) {
+                    res.status(err.status).json({ error: err.message, ...err.payload });
+                    return;
+                }
+                if (err instanceof WorkflowDomainError) {
+                    res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+                    return;
+                }
+                console.error('[plugins] rename failed:', err);
+                res.status(500).json({ error: 'Failed to rename the plugin' });
+            }
+        });
+    }
+    /**
+     * Linking shared skills — see `PluginLinksService` for the two-sided write.
+     *
+     *   POST   /api/plugins/:name/links          { skillPath }  → { root, skills }
+     *   DELETE /api/plugins/:name/links?skillPath=              → { root, revoked }
+     *   POST   /api/plugins/:name/links/repair   { skillPath }  → { root }
+     *
+     * Refusals carry a `kind` the UI branches on — `needs-skill-write` (409) is
+     * the one that becomes "request write access".
+     */
+    if (links) {
+        const linkOp = async (req, res, op, skillPathOf) => {
+            if (!req.userEmail) {
+                res.status(401).json({ error: 'Unauthenticated' });
+                return;
+            }
+            const user = await resolveUser(req);
+            if (!user) {
+                res.status(401).json({ error: 'Unauthenticated' });
+                return;
+            }
+            const skillPath = skillPathOf(req);
+            if (typeof skillPath !== 'string' || !skillPath.trim()) {
+                res.status(400).json({ error: 'skillPath is required' });
+                return;
+            }
+            try {
+                res.json(await op(user, String(req.params.name), skillPath));
+            }
+            catch (err) {
+                if (err instanceof PluginLinkError) {
+                    res.status(err.status).json({ error: err.message, ...err.payload });
+                    return;
+                }
+                if (err instanceof WorkflowDomainError) {
+                    res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+                    return;
+                }
+                console.error('[plugins] link operation failed:', err);
+                res.status(500).json({ error: 'Failed to update the plugin\'s links' });
+            }
+        };
+        const bodyPath = (req) => (req.body ?? {}).skillPath;
+        router.post('/plugins/:name/links', (req, res) => linkOp(req, res, (u, p, s) => links.link(u, p, s), bodyPath));
+        router.post('/plugins/:name/links/repair', (req, res) => linkOp(req, res, (u, p, s) => links.repair(u, p, s), bodyPath));
+        router.delete('/plugins/:name/links', (req, res) => linkOp(req, res, (u, p, s) => links.unlink(u, p, s), (r) => r.query.skillPath));
+    }
     /** The folder-chain probe for MEMBERSHIP — the folder itself. */
     const memberProbe = (folder) => folder;
     /** The FILE probe for discovery/management — the folder's access.md. */
     const accessMdOf = (folder) => `${folder}/access.md`;
+    /** A plugin folder's path BELOW the plugins root: `GTM`, or `teams/deep`. */
+    const folderBelowRoot = (folder) => folder.slice(folder.indexOf('/') + 1);
+    /**
+     * What a join request is keyed by: the plugin's primary FOLDER path below
+     * the root, not its identity. The request writes into that folder's rules;
+     * a top-level folder keys exactly as every join branch already on a remote
+     * was cut (its name), a nested one by its whole path, so two plugins whose
+     * folders share a basename never share a branch; and a rename of the
+     * identity moves no folder, so it orphans no open request.
+     */
+    const joinKeyOf = (g) => folderBelowRoot(g.folders[0]);
     const probesFor = (plugins) => [
         ...new Set(plugins.flatMap((g) => g.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]))),
     ];
@@ -90,15 +191,18 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
                 const discoverable = member || any(readable, g, accessMdOf);
                 if (!member && !manager && !discoverable)
                     continue; // absent — fail closed
-                const joinCr = member ? null : openJoinCr(mine, email, g.name);
+                const joinCr = member ? null : openJoinCr(mine, email, joinKeyOf(g));
                 plugins.push({
                     name: g.name,
+                    displayName: g.displayName,
                     folders: g.folders,
                     canRead: member,
                     canWrite: manager,
                     isOwner: owner,
+                    linksAreManaged: g.linksAreManaged,
                     skillCount: g.skillCount,
                     toolCount: g.toolCount,
+                    brokenLinks: g.brokenLinks,
                     owners: g.owners,
                     writers: g.writers,
                     readers: g.readers,
@@ -198,7 +302,7 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
                 res.status(401).json({ error: 'Unauthenticated' });
                 return;
             }
-            // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+            // By identity — the manifest name the catalog keys on.
             const plugin = (await pluginIndex.catalog()).find((g) => g.name === req.params.name);
             const wsId = pluginsWorkspaceId();
             const ownerVerdicts = plugin
@@ -208,7 +312,10 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
                 res.status(404).json({ error: 'Unknown plugin', kind: 'unknown-plugin' });
                 return;
             }
-            await provision.deletePlugin(user, plugin.name);
+            // Provisioning works on FOLDERS (it created one); the identity only
+            // found the plugin. The whole path below the root, so a nested plugin
+            // is deleted where it is.
+            await provision.deletePlugin(user, folderBelowRoot(plugin.folders[0]));
             pluginIndex.invalidate();
             res.json({ ok: true });
         }
@@ -234,7 +341,7 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
                 return;
             }
             const catalog = await pluginIndex.catalog();
-            // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+            // By identity — the manifest name the catalog keys on.
             const plugin = catalog.find((g) => g.name === req.params.name);
             const wsId = pluginsWorkspaceId();
             // Same ANY-folder shape `GET /plugins` resolves with, so a plugin can
@@ -258,8 +365,8 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
             // summary's `folders[0]` names and the banner's touched-path check
             // expects.
             const folder = plugin.folders[0];
-            const branch = joinBranchFor(email, plugin.name);
-            const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, plugin.name);
+            const branch = joinBranchFor(email, joinKeyOf(plugin));
+            const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, joinKeyOf(plugin));
             if (existing) {
                 res.json({ ok: true, number: existing.number });
                 return;
@@ -278,13 +385,14 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
             const spliced = spliceGrant(current, 'read', { kind: 'user', email: user.email, displayName: user.name }, { target: 'folder' });
             if (spliced.changed) {
                 await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-                await workflow.commitChanges(ws.id, user, `Request access to ${plugin.name}`);
+                await workflow.commitChanges(ws.id, user, `Request access to ${plugin.displayName}`);
             }
             const detail = await workflow.openChangeRequest(ws.id, user, {
                 sourceBranch: branch,
                 targetBranch: DEFAULT_BRANCH,
-                title: `Join request: ${plugin.name}`,
-                description: `${user.name} asked to join ${plugin.name}. A manager of the plugin accepts by ` +
+                // People read these: the display name, not the identifier.
+                title: `Join request: ${plugin.displayName}`,
+                description: `${user.name} asked to join ${plugin.displayName}. A manager of the plugin accepts by ` +
                     `granting the access this branch proposes; the request closes itself once ` +
                     `every proposal has landed.`,
             });
@@ -338,7 +446,7 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
                 return;
             const crs = await workflow.listChangeRequests();
             res.json({
-                requests: await joinRequests.list(ctx.plugin.name, ctx.folder, crs, ctx.user),
+                requests: await joinRequests.list(joinKeyOf(ctx.plugin), ctx.folder, crs, ctx.user),
             });
         }
         catch (err) {
@@ -367,7 +475,7 @@ export function createPluginsRoutes(pluginIndex, accessControl, workflow, worksp
                 res.status(404).json({ error: 'Not found' });
                 return;
             }
-            res.json({ closed: await joinRequests.reconcile(ctx.plugin.name, ctx.folder, cr, ctx.user) });
+            res.json({ closed: await joinRequests.reconcile(joinKeyOf(ctx.plugin), ctx.folder, cr, ctx.user) });
         }
         catch (err) {
             console.error('[plugins] failed to reconcile a join request:', err);