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

package/dist/modules/plugins/join-proposals.d.ts

@@ -0,0 +1,53 @@
+import { type Verb } from '../access/access-control.service.js';
+/**
+ * What a join branch is PROPOSING, relative to the default branch.
+ *
+ * A join request is a change request whose branch edits one plugin's
+ * `access.md`. Rather than treating that change request as an all-or-nothing
+ * merge, the plugin's managers see its individual proposals — "grant Ali read",
+ * "grant GTM Team write" — and answer them one at a time. Approving a proposal
+ * writes THAT ONE grant onto the default branch through the ordinary access
+ * mutation path; the branch is never merged, so nothing else it happens to
+ * contain can ride along, and a change request naming five people can be
+ * answered with two yeses and three ignores.
+ *
+ * A proposal is any (principal, verb) GRANT the branch's copy of the file
+ * carries that the default branch's copy does not. Deliberately:
+ *
+ *  - grants only. A `deny` entry is not something to "accept", and a branch
+ *    that REMOVES an existing grant proposes nothing — it is a revocation,
+ *    which is not what this surface is for. Both are simply invisible here,
+ *    and both leave the branch as a normal change request in the review UI.
+ *  - every verb, not just `read`. A branch asking for `write` must be visible
+ *    AS a write request rather than hiding behind "asked to join"; and the
+ *    subset test that retires a request has to cover everything the file can
+ *    express, or a request proposing `write` would never settle.
+ *
+ * When the list comes back EMPTY the branch adds nothing the default branch
+ * does not already grant — its proposals have all been accepted (or were
+ * never anything) — and the change request has no reason to stay open.
+ */
+export interface JoinProposal {
+    verb: Verb;
+    /** Canonical identity — lowercased email, or canonical role name. */
+    id: string;
+    principal: {
+        kind: 'user';
+        email: string;
+        displayName: string;
+    } | {
+        kind: 'role';
+        role: string;
+    };
+    /** How to name this principal in the UI. */
+    label: string;
+}
+/**
+ * The grants `branchText` adds over `defaultText` — the proposals a manager
+ * can accept. Empty ⇒ the branch's rules are a subset of the default's.
+ *
+ * `path` is only used to label parse errors; both texts are the same file at
+ * two refs.
+ */
+export declare function pendingProposals(branchText: string | null, defaultText: string | null, path: string): JoinProposal[];
+//# sourceMappingURL=join-proposals.d.ts.map

package/dist/modules/plugins/join-proposals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-proposals.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/join-proposals.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,IAAI,EACV,MAAM,qCAAqC,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EACL;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GACpD;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAgCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,IAAI,EAAE,MAAM,GACX,YAAY,EAAE,CA0BhB"}

package/dist/modules/plugins/join-proposals.js

@@ -0,0 +1,67 @@
+import { KNOWN_VERBS, parseAccessFile, } from '../access/access-control.service.js';
+/** Canonical identity of an entry, for set comparison across the two files. */
+function identityOf(entry) {
+    return entry.kind === 'user' ? `user:${entry.email}` : `role:${entry.role}`;
+}
+/**
+ * Folder rules from one copy of an `access.md`, per verb, grants only.
+ *
+ * A file that fails to parse yields NO grants. On the branch side that means
+ * a malformed proposal offers nothing to accept (fail-closed). On the default
+ * side it means every branch grant looks incoming — which is the safe
+ * direction too: the manager is shown proposals to consider rather than
+ * having them silently swallowed by an unreadable baseline.
+ */
+function grantsByVerb(text, path) {
+    const out = new Map();
+    for (const verb of KNOWN_VERBS)
+        out.set(verb, new Map());
+    if (text === null)
+        return out;
+    const parsed = parseAccessFile(text, path);
+    if (!parsed.ok)
+        return out;
+    for (const verb of KNOWN_VERBS) {
+        const byId = out.get(verb);
+        for (const entry of parsed.file.entries[verb]) {
+            if (entry.deny)
+                continue;
+            byId.set(identityOf(entry), entry);
+        }
+    }
+    return out;
+}
+/**
+ * The grants `branchText` adds over `defaultText` — the proposals a manager
+ * can accept. Empty ⇒ the branch's rules are a subset of the default's.
+ *
+ * `path` is only used to label parse errors; both texts are the same file at
+ * two refs.
+ */
+export function pendingProposals(branchText, defaultText, path) {
+    const branch = grantsByVerb(branchText, path);
+    const base = grantsByVerb(defaultText, path);
+    const out = [];
+    for (const verb of KNOWN_VERBS) {
+        const baseIds = base.get(verb);
+        for (const [id, entry] of branch.get(verb)) {
+            if (baseIds.has(id))
+                continue;
+            out.push(entry.kind === 'user'
+                ? {
+                    verb,
+                    id,
+                    principal: { kind: 'user', email: entry.email, displayName: entry.displayName },
+                    label: entry.displayName,
+                }
+                : {
+                    verb,
+                    id,
+                    principal: { kind: 'role', role: entry.displayRole },
+                    label: entry.displayRole,
+                });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=join-proposals.js.map

package/dist/modules/plugins/join-proposals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-proposals.js","sourceRoot":"","sources":["../../../src/modules/plugins/join-proposals.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,eAAe,GAGhB,MAAM,qCAAqC,CAAC;AAyC7C,+EAA+E;AAC/E,SAAS,UAAU,CAAC,KAAkB;IACpC,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,YAAY,CAAC,IAAmB,EAAE,IAAY;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkC,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,WAAW;QAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;IACzD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IAC9B,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,IAAI,KAAK,CAAC,IAAI;gBAAE,SAAS;YACzB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAAyB,EACzB,WAA0B,EAC1B,IAAY;IAEZ,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,YAAY,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QAChC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAE,EAAE,CAAC;YAC5C,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC9B,GAAG,CAAC,IAAI,CACN,KAAK,CAAC,IAAI,KAAK,MAAM;gBACnB,CAAC,CAAC;oBACE,IAAI;oBACJ,EAAE;oBACF,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE;oBAC/E,KAAK,EAAE,KAAK,CAAC,WAAW;iBACzB;gBACH,CAAC,CAAC;oBACE,IAAI;oBACJ,EAAE;oBACF,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,EAAE;oBACpD,KAAK,EAAE,KAAK,CAAC,WAAW;iBACzB,CACN,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/modules/plugins/join-requests.service.d.ts

@@ -0,0 +1,81 @@
+import { type AuthUser, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import { type WorkspaceService } from '../workspace/workspace.service.js';
+import { type JoinProposal } from './join-proposals.js';
+/** One open join change request, with what it still proposes. */
+export interface JoinRequest {
+    number: number;
+    branch: string;
+    requesterName: string;
+    createdAt: string;
+    /** Grants the branch adds over the default branch. Never empty (see below). */
+    proposals: JoinProposal[];
+}
+/**
+ * Join requests as PROPOSALS, and the reconciliation that retires them.
+ *
+ * The lifecycle has no state of its own — it is derived, every time, from two
+ * copies of one file:
+ *
+ *   open        the branch's `access.md` grants something the default's does not
+ *   settled     it does not
+ *
+ * so "approve" is not an operation on the request at all. A manager grants a
+ * principal through the ordinary access path (the same lock + commit every
+ * other access edit uses, gated the same way), the default branch gains that
+ * entry, and the proposal stops being pending because the diff no longer
+ * contains it. When the last one goes, the change request has nothing left to
+ * say and is rejected, its branch deleted.
+ *
+ * That reconciliation runs LAZILY on every listing as well as on demand, so a
+ * grant made anywhere — this banner, the Manage-access dialog, a hand edit —
+ * settles the request that asked for it. Nothing has to remember to.
+ */
+export declare class JoinRequestsService {
+    private readonly workspaceService;
+    private readonly workflow;
+    constructor(workspaceService: WorkspaceService, workflow: IWorkflowService);
+    /**
+     * Open join requests for `plugin`, each carrying only its still-pending
+     * proposals. Requests with none left are reconciled away (rejected, branch
+     * deleted) and omitted.
+     *
+     * `actor` is who the reconciliation acts as — a manager of the plugin, since
+     * rejecting a change request requires write on everything it touches.
+     */
+    list(plugin: string, folder: string, crs: ChangeRequest[], actor: AuthUser): Promise<JoinRequest[]>;
+    /**
+     * Re-check ONE request and settle it if nothing is pending. Returns whether
+     * it was settled. Called right after a grant so the banner updates in the
+     * same round-trip instead of waiting for the next listing.
+     */
+    reconcile(plugin: string, folder: string, cr: ChangeRequest, actor: AuthUser): Promise<boolean>;
+    /**
+     * Close a request whose proposals have all landed, and delete its branch.
+     *
+     * Rejecting rather than merging is the point: the grants are already on the
+     * default branch, so merging would replay a diff that is now empty of
+     * meaning while dragging along anything else the branch carries. The branch
+     * goes too — it exists only to hold a proposal that no longer exists.
+     *
+     * Best-effort by contract: this runs inside a listing, and a request that
+     * cannot be closed right now must not take the listing down with it. The
+     * next pass tries again.
+     */
+    private settle;
+    /**
+     * The file at one branch, or null when it is absent/unreadable there.
+     *
+     * Every read runs against the DEFAULT branch's clone at `origin/<branch>`,
+     * so one workspace answers for every request and a join branch never needs
+     * a clone of its own. `readFileAtRef` takes a REPO-relative path (the KB
+     * dir is the repo root there).
+     */
+    private readAt;
+    /**
+     * Refresh remote-tracking refs before reading them. Throttled inside, and
+     * best-effort: a request pushed seconds ago is worth one fetch, but a fetch
+     * failure must degrade to "read what we have" rather than empty the list.
+     */
+    private refresh;
+}
+//# sourceMappingURL=join-requests.service.d.ts.map

package/dist/modules/plugins/join-requests.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-requests.service.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/join-requests.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE1E,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE,gBAAgB;IAG7C;;;;;;;OAOG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,aAAa,EAAE,EACpB,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,WAAW,EAAE,CAAC;IA2BzB;;;;OAIG;IACG,SAAS,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,OAAO,CAAC;IAcnB;;;;;;;;;;;OAWG;YACW,MAAM;IAgCpB;;;;;;;OAOG;YACW,MAAM;IAYpB;;;;OAIG;YACW,OAAO;CAKtB"}

package/dist/modules/plugins/join-requests.service.js

@@ -0,0 +1,135 @@
+import { DEFAULT_BRANCH, isJoinBranchFor, } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { pendingProposals } from './join-proposals.js';
+/**
+ * Join requests as PROPOSALS, and the reconciliation that retires them.
+ *
+ * The lifecycle has no state of its own — it is derived, every time, from two
+ * copies of one file:
+ *
+ *   open        the branch's `access.md` grants something the default's does not
+ *   settled     it does not
+ *
+ * so "approve" is not an operation on the request at all. A manager grants a
+ * principal through the ordinary access path (the same lock + commit every
+ * other access edit uses, gated the same way), the default branch gains that
+ * entry, and the proposal stops being pending because the diff no longer
+ * contains it. When the last one goes, the change request has nothing left to
+ * say and is rejected, its branch deleted.
+ *
+ * That reconciliation runs LAZILY on every listing as well as on demand, so a
+ * grant made anywhere — this banner, the Manage-access dialog, a hand edit —
+ * settles the request that asked for it. Nothing has to remember to.
+ */
+export class JoinRequestsService {
+    workspaceService;
+    workflow;
+    constructor(workspaceService, workflow) {
+        this.workspaceService = workspaceService;
+        this.workflow = workflow;
+    }
+    /**
+     * Open join requests for `plugin`, each carrying only its still-pending
+     * proposals. Requests with none left are reconciled away (rejected, branch
+     * deleted) and omitted.
+     *
+     * `actor` is who the reconciliation acts as — a manager of the plugin, since
+     * rejecting a change request requires write on everything it touches.
+     */
+    async list(plugin, folder, crs, actor) {
+        await this.refresh();
+        const accessPath = `${folder}/access.md`;
+        const baseText = await this.readAt(DEFAULT_BRANCH, accessPath);
+        const out = [];
+        for (const cr of crs) {
+            if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin))
+                continue;
+            const proposals = pendingProposals(await this.readAt(cr.branch, accessPath), baseText, accessPath);
+            if (proposals.length === 0) {
+                await this.settle(cr, actor);
+                continue;
+            }
+            out.push({
+                number: cr.number,
+                branch: cr.branch,
+                requesterName: cr.appAuthor?.name ?? 'Someone',
+                createdAt: cr.createdAt,
+                proposals,
+            });
+        }
+        return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    /**
+     * Re-check ONE request and settle it if nothing is pending. Returns whether
+     * it was settled. Called right after a grant so the banner updates in the
+     * same round-trip instead of waiting for the next listing.
+     */
+    async reconcile(plugin, folder, cr, actor) {
+        if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin))
+            return false;
+        await this.refresh();
+        const accessPath = `${folder}/access.md`;
+        const proposals = pendingProposals(await this.readAt(cr.branch, accessPath), await this.readAt(DEFAULT_BRANCH, accessPath), accessPath);
+        if (proposals.length > 0)
+            return false;
+        await this.settle(cr, actor);
+        return true;
+    }
+    /**
+     * Close a request whose proposals have all landed, and delete its branch.
+     *
+     * Rejecting rather than merging is the point: the grants are already on the
+     * default branch, so merging would replay a diff that is now empty of
+     * meaning while dragging along anything else the branch carries. The branch
+     * goes too — it exists only to hold a proposal that no longer exists.
+     *
+     * Best-effort by contract: this runs inside a listing, and a request that
+     * cannot be closed right now must not take the listing down with it. The
+     * next pass tries again.
+     */
+    async settle(cr, actor) {
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        try {
+            await this.workflow.rejectChangeRequest(cr.number, actor, cr.state, cr.authorId ?? null, cr.base, wsId);
+        }
+        catch (err) {
+            console.warn(`[plugins] could not close settled join request #${cr.number}: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        try {
+            await this.workflow.deleteBranch(wsId, cr.branch, actor);
+        }
+        catch (err) {
+            // The request is closed either way; a leftover branch is cosmetic and
+            // the author can still delete it themselves.
+            console.warn(`[plugins] closed join request #${cr.number} but could not delete "${cr.branch}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * The file at one branch, or null when it is absent/unreadable there.
+     *
+     * Every read runs against the DEFAULT branch's clone at `origin/<branch>`,
+     * so one workspace answers for every request and a join branch never needs
+     * a clone of its own. `readFileAtRef` takes a REPO-relative path (the KB
+     * dir is the repo root there).
+     */
+    async readAt(branch, repoRelPath) {
+        try {
+            return await this.workspaceService.readFileAtRef(workspaceIdForBranch(DEFAULT_BRANCH), `origin/${branch}`, repoRelPath);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Refresh remote-tracking refs before reading them. Throttled inside, and
+     * best-effort: a request pushed seconds ago is worth one fetch, but a fetch
+     * failure must degrade to "read what we have" rather than empty the list.
+     */
+    async refresh() {
+        await this.workspaceService
+            .ensureRemotesFetched(workspaceIdForBranch(DEFAULT_BRANCH))
+            .catch(() => undefined);
+    }
+}
+//# sourceMappingURL=join-requests.service.js.map

package/dist/modules/plugins/join-requests.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-requests.service.js","sourceRoot":"","sources":["../../../src/modules/plugins/join-requests.service.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,eAAe,GAIhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAyB,MAAM,mCAAmC,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAqB,MAAM,qBAAqB,CAAC;AAY1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,mBAAmB;IAEX;IACA;IAFnB,YACmB,gBAAkC,EAClC,QAA0B;QAD1B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,aAAQ,GAAR,QAAQ,CAAkB;IAC1C,CAAC;IAEJ;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CACR,MAAc,EACd,MAAc,EACd,GAAoB,EACpB,KAAe;QAEf,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,GAAG,MAAM,YAAY,CAAC;QACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAkB,EAAE,CAAC;QAC9B,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,EAAE,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAAE,SAAS;YACzE,MAAM,SAAS,GAAG,gBAAgB,CAChC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,EACxC,QAAQ,EACR,UAAU,CACX,CAAC;YACF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;gBAC7B,SAAS;YACX,CAAC;YACD,GAAG,CAAC,IAAI,CAAC;gBACP,MAAM,EAAE,EAAE,CAAC,MAAM;gBACjB,MAAM,EAAE,EAAE,CAAC,MAAM;gBACjB,aAAa,EAAE,EAAE,CAAC,SAAS,EAAE,IAAI,IAAI,SAAS;gBAC9C,SAAS,EAAE,EAAE,CAAC,SAAS;gBACvB,SAAS;aACV,CAAC,CAAC;QACL,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CACb,MAAc,EACd,MAAc,EACd,EAAiB,EACjB,KAAe;QAEf,IAAI,EAAE,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7E,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,GAAG,MAAM,YAAY,CAAC;QACzC,MAAM,SAAS,GAAG,gBAAgB,CAChC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,EACxC,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,EAC7C,UAAU,CACX,CAAC;QACF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;OAWG;IACK,KAAK,CAAC,MAAM,CAAC,EAAiB,EAAE,KAAe;QACrD,MAAM,IAAI,GAAG,oBAAoB,CAAC,cAAc,CAAC,CAAC;QAClD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CACrC,EAAE,CAAC,MAAM,EACT,KAAK,EACL,EAAE,CAAC,KAAK,EACR,EAAE,CAAC,QAAQ,IAAI,IAAI,EACnB,EAAE,CAAC,IAAI,EACP,IAAI,CACL,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,mDAAmD,EAAE,CAAC,MAAM,KAC1D,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;YACF,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sEAAsE;YACtE,6CAA6C;YAC7C,OAAO,CAAC,IAAI,CACV,kCAAkC,EAAE,CAAC,MAAM,0BAA0B,EAAE,CAAC,MAAM,MAC5E,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,WAAmB;QACtD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,CAC9C,oBAAoB,CAAC,cAAc,CAAC,EACpC,UAAU,MAAM,EAAE,EAClB,WAAW,CACZ,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,OAAO;QACnB,MAAM,IAAI,CAAC,gBAAgB;aACxB,oBAAoB,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC;aAC1D,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/modules/plugins/plugin-provision.service.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 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 `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.
+ *
+ * What a provision IS: one exclusive write of the new folder's `access.md`
+ * (flag `wx`, so two concurrent creators race for the fs, not for the
+ * overwrite), then one SYNCHRONOUS commit+push. Synchronous on purpose — the
+ * write gate reads rules at HEAD, so a creation whose access.md were still
+ * sitting in the async commit queue would 403 the very next thing its
+ * creator does (writing the first skill into it).
+ *
+ * Two shapes, two templates:
+ *
+ *   - 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
+ *     frontmatter grant at all, so nobody else can even see it exists; the
+ *     body names its owner. Created lazily (ensure semantics) on the first
+ *     personal skill.
+ */
+import { type AuthUser } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+/** Commit machinery the provision rides — the pending-commit pipeline, run inline. */
+export interface ProvisionCommitDriver {
+    runPendingCommit(workspaceId: string, branch: string, targetPath: string, user: AuthUser, opts?: {
+        systemAuthorized?: boolean;
+    }): Promise<void>;
+}
+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 declare class PluginProvisionError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class PluginProvisionService {
+    private readonly workspaceService;
+    private readonly commits;
+    private readonly accessControl;
+    private readonly kbDirName;
+    private readonly events?;
+    /**
+     * 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;
+    constructor(workspaceService: WorkspaceService, commits: ProvisionCommitDriver, accessControl: IAccessControl, kbDirName: string, events?: {
+        emit(event: {
+            kind: "fs-tree-changed";
+            workspaceId: string;
+            branch: string;
+        }): void;
+    } | undefined);
+    /**
+     * 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).
+     */
+    createPlugin(user: AuthUser, rawName: string): Promise<ProvisionedPlugin>;
+    /**
+     * Ensure the caller's personal folder exists — idempotent, keyed to the
+     * stable user id. Returns `created: false` when it is already there.
+     */
+    ensurePersonalPlugin(user: AuthUser): Promise<ProvisionedPlugin>;
+    /**
+     * 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 `createPlugin` leaves
+     * "any signed-in user" to its endpoint.
+     *
+     * Shape mirrors a provision run in reverse, with the same failure
+     * contract: the folder is PARKED (renamed to a dot-prefixed sibling the
+     * 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
+     * plugin exactly as it was — never half-gone on disk while origin still
+     * carries it.
+     *
+     * 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).
+     */
+    deletePlugin(user: AuthUser, rawName: string): Promise<void>;
+    /** The taken name (in its on-disk casing) colliding with `name`, or null. */
+    private existingFolder;
+    /** An existing PLUGIN FOLDER whose derived manifest name equals `name`'s, or null. */
+    private manifestNameTwin;
+    private provision;
+    private readyWorkspaceId;
+}
+/**
+ * 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 declare function pluginAccessMd(creator: {
+    name: string;
+    email: string;
+}): string;
+/**
+ * A personal folder's access.md: PRIVATE — no frontmatter grant, so the
+ * folder is invisible to everyone but its owner; the body names the owner
+ * under read, write and owner.
+ */
+export declare function personalAccessMd(creator: {
+    name: string;
+    email: string;
+}): string;
+//# sourceMappingURL=plugin-provision.service.d.ts.map

package/dist/modules/plugins/plugin-provision.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-provision.service.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugin-provision.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,EASL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAK5E,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CACd,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,GACpC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,mEAAmE;AACnE,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAED,qBAAa,sBAAsB;IAY/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAf1B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;gBAG/B,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,EAAE,qBAAqB,EAC9B,aAAa,EAAE,cAAc,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE;YAAE,IAAI,EAAE,iBAAiB,CAAC;YAAC,WAAW,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,YAAA;IAGnH;;;;;OAKG;IACG,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuD/E;;;OAGG;IACG,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqBtE;;;;;;;;;;;;;;;;;;OAkBG;IACG,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDlE,6EAA6E;YAC/D,cAAc;IAa5B,sFAAsF;YACxE,gBAAgB;YA0BhB,SAAS;YA4DT,gBAAgB;CAI/B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEjF"}