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

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

@@ -25,11 +25,13 @@
  *     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.
+ *   - A PERSONAL folder (`personal-<user-id>`): private by design, in both
+ *     blocks. The frontmatter denies `everyone` and names only the owner,
+ *     so nobody else can even see it exists; the body says the same of the
+ *     folder. Created lazily (ensure semantics) on the first personal skill.
  */
+import type { IFsProbe } from '../../shared/fs.contract.js';
+import type { PluginSource } from './discovery/plugin-source.js';
 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';
@@ -40,8 +42,20 @@ export interface ProvisionCommitDriver {
     }): Promise<void>;
 }
 export interface ProvisionedPlugin {
-    /** The folder name under `Plugins/` (not the full path). */
+    /** The folder's path below `Plugins/` — `GTM`, or `Teams/GTM` for one made inside a grouping folder. */
     folder: string;
+    /** The same folder, repo-relative — `Plugins/Teams/GTM` — as the file tools address it. */
+    path: string;
+    /** Where its skills go: `<path>/skills`, each skill a subfolder holding a `SKILL.md`. */
+    skillsDir: string;
+    /** The plugin's identity — the manifest name written for it. */
+    name: string;
+    /**
+     * What a person sees it called — the manifest's `displayName`, which is the
+     * name the creator typed, trimmed. Exactly as persisted: the answer and the
+     * file on disk can never say two different things.
+     */
+    displayName: string;
     /** False when an ensure found the folder already there. */
     created: boolean;
 }
@@ -55,7 +69,10 @@ export declare class PluginProvisionService {
     private readonly commits;
     private readonly accessControl;
     private readonly kbDirName;
-    private readonly events?;
+    private readonly events;
+    /** Which names are TAKEN is discovery's answer — the same one every catalog gets. */
+    private readonly source;
+    private readonly disk;
     /**
      * Serialises creations and deletions by MANIFEST SLUG
      * (`pluginManifestName(name)`). The wx write arbitrates same-path races,
@@ -65,23 +82,46 @@ export declare class PluginProvisionService {
      * name can hold the lock at once.
      */
     private readonly creations;
-    constructor(workspaceService: WorkspaceService, commits: ProvisionCommitDriver, accessControl: IAccessControl, kbDirName: string, events?: {
+    constructor(workspaceService: WorkspaceService, commits: ProvisionCommitDriver, accessControl: IAccessControl, kbDirName: string, events: {
         emit(event: {
-            kind: "fs-tree-changed";
+            kind: 'fs-tree-changed';
             workspaceId: string;
             branch: string;
         }): void;
-    } | undefined);
+    } | undefined, 
+    /** Which names are TAKEN is discovery's answer — the same one every catalog gets. */
+    source: PluginSource, disk: IFsProbe);
+    /**
+     * Create `Plugins/<name>/` — or `Plugins/<parent>/<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), 404 when `parent` names no folder.
+     *
+     * `parent` is a GROUPING folder below the plugins root (`Teams`,
+     * `Teams/EU`): it must exist, and it must not be a plugin or sit inside
+     * one — discovery claims a plugin's whole subtree, so a plugin made there
+     * would be invisible to every catalog. The identity checks are the same at
+     * any depth: a nested plugin claims its slug as fully as a top-level one.
+     */
+    createPlugin(user: AuthUser, rawName: string, rawParent?: string): Promise<ProvisionedPlugin>;
     /**
-     * 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).
+     * The grouping folder a creation goes into, as its path below the plugins
+     * root — `''` for the root itself. Validated AS GIVEN, segment by segment,
+     * with the one rule every path here obeys (`validateFilename`, no
+     * dot-prefix); it must exist with every component spelled as on disk; and
+     * it must be a GROUPING folder — not a personal space, not a plugin, not
+     * inside one, since discovery claims a plugin's subtree and a plugin made
+     * there would be listed nowhere. A hole in discovery refuses, as for every
+     * other provisioning write.
      */
-    createPlugin(user: AuthUser, rawName: string): Promise<ProvisionedPlugin>;
+    private resolveParent;
     /**
      * Ensure the caller's personal folder exists — idempotent, keyed to the
-     * stable user id. Returns `created: false` when it is already there.
+     * stable user id. Returns `created: false` when it is already there, and
+     * with it the display name the existing manifest carries (see
+     * {@link persistedDisplayName}): the answer is what the file says, so the
+     * call that made the folder and every call after it agree.
      */
     ensurePersonalPlugin(user: AuthUser): Promise<ProvisionedPlugin>;
     /**
@@ -103,11 +143,58 @@ export declare class PluginProvisionService {
      * 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. */
+    deletePlugin(user: AuthUser, rawFolder: string): Promise<void>;
+    /**
+     * Whether `segments` names a directory below `root` with every component
+     * spelled exactly as on disk — by listing each level, which is the one
+     * question a case-insensitive filesystem answers honestly.
+     */
+    private exactFolderExists;
+    /**
+     * The taken name (in its on-disk casing) colliding with `name` in `parent`
+     * (`''` = the plugins root), or null.
+     */
     private existingFolder;
-    /** An existing PLUGIN FOLDER whose derived manifest name equals `name`'s, or null. */
+    /**
+     * What the plugin at `folder` is ALREADY called, read from its manifest by
+     * the one shared rule — `fallback` only when there is no manifest to read
+     * (a folder mid-creation, a `plugin.json` that is not an object).
+     *
+     * An ensure that found the folder already there answers with the FILE's
+     * answer, never the folder's spelling: the folder is an input to no name,
+     * and an idempotent call whose second answer differed from its first would
+     * be this service telling the caller a plugin had been renamed.
+     */
+    private persistedDisplayName;
+    /**
+     * The identity discovery gives the plugin at `folder`, or the folder's own
+     * slug when it lists none there. ONE rule for every write provisioning
+     * makes — create, delete — as for the rename: no write over a discovery
+     * with a hole in it, whether or not the hole is where this plugin lives.
+     * An operation that parks and commits against an identity set it could
+     * not fully see is the class of mistake the rule exists to make impossible.
+     */
+    private discoveredIdentity;
+    /** One discovery over the knowledge base checkout. */
+    private discovered;
+    /**
+     * An existing plugin — at ANY depth, in either file shape — whose identity
+     * folds to the same slug as `name`'s, as its repo-relative folder; or null.
+     * Discovery's answer, so creation and every catalog agree on what is taken:
+     * a nested plugin claims its identity as fully as a top-level one, and a
+     * parked delete (dot-prefixed, invisible to the walk) claims nothing.
+     * Personal folders count — they publish a plugin.json like any plugin
+     * (though the reservation above means a named plugin never reaches this
+     * check with a personal slug). A loose file at the root is not a plugin.
+     *
+     * Refuses on a HOLE: a listing that could not see part of the tree cannot
+     * prove a name free.
+     */
     private manifestNameTwin;
+    /**
+     * Seed `Plugins/<folder>/` — `folder` being the path below the root, `leaf`
+     * its last segment, which names the manifest — and commit it.
+     */
     private provision;
     private readyWorkspaceId;
 }
@@ -117,15 +204,36 @@ export declare class PluginProvisionService {
  * (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.
+ *
+ * The comments are part of the template on purpose. The file is what an
+ * administrator opens to widen a plugin, and the two blocks look alike: a
+ * person who finds `everyone` already under the top `read:` and adds nothing
+ * concludes that "everyone" does nothing. Each block says what it governs,
+ * and the body says how to admit people, right where they would type it.
+ * `spliceGrant` preserves comments, so every later edit keeps them.
  */
 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.
+ * A personal folder's access.md: PRIVATE, in both blocks. The body DENIES
+ * `everyone` read outright, so a `read: everyone` an administrator later
+ * adds at the repo root (the usual way to open the knowledge base up) cannot
+ * open every person's private space with it, and names the owner directly,
+ * which outranks the denial. The frontmatter says the same of the FILE — so
+ * the folder's listing is invisible to everyone but the owner, and so the
+ * file states its own privacy where a reader (and the Library's "Private"
+ * mark, see `isPrivateAccessMd`) looks for it, rather than leaving it to
+ * what an empty block happens to inherit. Nobody else is named — not even
+ * Admin: a private space is private from the people who run the deployment
+ * too. (An administrator can still write this file, through the resolver's
+ * access.md rescue, and so grant themselves in; that is a visible act in
+ * the history, not a default.)
+ *
+ * The frontmatter is also what marks the file as body-governed. Without it
+ * the splicer (and the resolver) read the older single-block format, where
+ * the frontmatter IS the folder's rules.
  */
 export declare function personalAccessMd(creator: {
     name: string;

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

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